WorkBoard API v1.0

Overview

WorkBoard's API allows developers to write out-of-the-box applications to interact with WorkBoard in more complex ways than are available with our other built-in integrations.

For instance, you could use the API to automatically update Sales metrics from a CRM. Update user profile data from a central HR system. Pull data on goal progress into your organization's business reporting software to easily share results.

The WorkBoard API is organized around REST and provides programmatic access to much of your data in the system. Our API is designed to have predictable, resource-oriented URLs. We use built-in HTTP features to receive commands and return responses, and the API returns JSON content in all responses, including errors.

To facilitate your development process, your account will include both test-mode and live-mode API keys. These keys can be active at the same time.

All resources must be called using HTTPS and must include an access_token for authentication.

If you need to make API calls on all objects that belong to your organization on WorkBoard, please contact us to request data admin API access for your organization.

In addition to the API, you can also use Webhooks to dynamically update WorkBoard metric data from cron, Excel or Google spreadsheets, and your other business applications.

Authentication

Each call you make to the API must be authenticated with an access token. WorkBoard offers two methods for requesting an access token: instant tokens, and OAuth 2.0 authentication.

If you are testing the API or are developing a single-user application, you can get an access token with a single click using Instant Token Authentication.

However, if you are developing an app for multiple users, we recommend using OAuth 2.0 for authentication. This will allow WorkBoard to dynamically authenticate any of your app users to give them access.

Note, as of August 5, 2019, you will no longer be able to pass your access token as an URL parameter in your request. Instead, we will require you to pass your access token as a bearer in the Authorization header.

Errors

Sometimes requests to the API are not successful. Failures can occur for a wide range of reasons.

Every response from WorkBoard's API will include success and message parameters. The success parameter indicates whether or not the request was successfully made, while the message parameter can help you debug problems.

Error	Description
invalid_client_id	The client id is invalid. Check the Client ID you received when you registered your app.
invalid_client_hash	The client hash doesn't exist or is invalid. Check the client hash you received when you registered your app.
invalid_auth_code	The authorization code doesn't exist or is invalid. Check the code you received during the oAuth 2.0 authentication process. Note that your authorization code is valid for 5 minutes and will expire if not exchanged for an access token within that time.
invalid_access_token	The access token is invalid. Check the access token you received during either the oAuth 2.0 or instant token authentication process.
auth_code_expired	The authorization token has expired. Your authentication token is valid for 1 year.
invalid_redirect_uri	The redirect URI is missing or does not match the one you provided when registering your app.
invalid_resource_id	The resource id doesn't exist or is invalid.
insufficient_access	You don't have access to the requested resource. Check the resource id.
missing_required_parameters	Your request did not pass all of the required parameters for the resource.
invalid_webhook_url	The webhook URL is missing or does not match any valid webhook.
invalid_webhook_action	The webhook action doesn't exist or is invalid for the request.
invalid_webhook_secret	The webhook signature doesn't match or is invalid for the subscribed webhook.

# Sample Success Response
{
    "success" : true,
    "message" : "Goal was created successfully",
    "data" : [
        "totalCount" : 10,
        "goal" : [
            {
              "Goal_id" : 123,
              "goal_name" : "test goal",
              ..
            },
        ..
        ]
    ]
}

# Sample Error Response
{
    "success" : false,
    "message" : " Verify goal id",
    "error" : "invalid_goal_id",
    "error_description" : "The resource doesn\'t belong to any goal that you have access to"
}

API Reference

You are viewing the improved API Reference documentation.
To view the legacy API Reference documentation click here.

We have improved API Reference documentation available for our API.
To view the improved API Reference documentation click here.

WorkBoard's API provides resources to allow developers to interact with user, goal, and metric data in WorkBoard. All resources can be accessed via REST with GET, POST, PUT, and DELETE requests.

For GET requests, query parameters can be passed either as part of the request URL or in the payload.

All GET, POST and PUT requests must include the token parameter, with the value set to the access_token you received during the authorization process.

# Standard GET response format
{
    "success"   : bool,
    "message" : "Machine readable message",
    "data"    :  [
        "totalCount" : "Resource count",
        "{resource_name}" : {resource_data}
    ]
}

Users

The User resource represents a user's WorkBoard profile data, including user id, first and last name, email address, company and title. Use the User resource to request or update WorkBoard user profile data, create new users, modify user reporting structures, or delete users.

Resource URL : https://www.myworkboard.com/wb/apis/user

The following attributes are associated with the User resource:

Attribute	Description
user_id	Read Only. The unique numerical id assigned to each user in WorkBoard
email	The user's email address
first_name	The user's first name
last_name	The user's last name
wb_email	The myworkboard.com email address assigned to the user (this email address is used to add action items via email)
cell_num	The user's mobile phone number
create_at	The user's account creation date (in Unix timestamp format)
last_visit_at	The user's last login date (in Unix timestamp format)
picture	The public URL for the user's profile picture
time_zone	The user's timezone
org_id	The unique numerical id assigned to each organization in WorkBoard. (Get the org_id with the user resource — don't specify a user_id in your request)
external_id	A user's unique numerical id from a system other than WorkBoard.
created_from	If a user is created from a system other than WorkBoard, the source of the user as a string.
profile	The user's job title and company name (as an array).

Get user profile

GET  /user/{user_id}

Request profile information for the authenticated user, including first name, last name, company, email address, and account creation date.

Parameters
user_id	Read Only. The unique numerical id assigned to each user in WorkBoard. If this parameter is not included, the response will include profile data for the current authenticated user.
opt_filters	Optional. If you have provisioned your users with a unique identifier generated by your system, then you can query them with this attribute. opt_filters can be set to a JSON with the following format: opt_filters= {"external_id":["externalids"]} — where "externalids" is an array of the external ids. Example: opt_filters= {"external_id": ["a123bc", "ax123b"]}
include	Returns a set of users: permitted values are "org_members" and "team_members". org_members — if the current authenticated user is an org admin, pass this value to return a dump of all organization members. team_members — pass this value to return a dump of all members from teams to which the current authenticated user has access.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/user/"

# Sample Response

{
  "success":true,
  "message":"",
  "data":{
    "totalCount":1,
    "user":{
      "user_id":"30895",
      "user_name":"",
      "email":"mary.cmoso@kikasco.com",
      "first_name":"Mary",
      "last_name":"Cmoso",
      "wb_email":"mary.cmoso",
      "cell_num":"+18503344221",
      "create_at":1418756866,
      "last_visited_at":"1543363490",
      "picture":"https://files-workboard-prod.s3.amazonaws.com/318fe8aeb139/original/?AWSAccessKeyId=AKIAIZKB&Expires=147596&Signature=D7S6Hnnkzbu",
      "time_zone":"America\/Los_Angeles",
      "external_id":null,
      "org_id":"2",
      "manager": [{
        "user_id":"30893",
        "email":"jack.ceomack@kikasco.com",
        "first_name":"Jack",
        "last_name":"Ceomack",
        "external_id":null,
        "role":"1"
      }],
      "profile":{
        "title":"CMO",
        "company":"Kikasco",
        "custom_attributes": [{
          "id":"7",
          "name":"Gender",
          "value":"Female"
        }]
      }
    }
  }
}

Create a new user

POST  /user

Create a new user in the organization. Include the user's profile attributes (first name, last name, company, title and cell phone) as parameters in your API call. You can also optionally set the new user's direct reporting manager.

Parameters
email	The user's email address
first_name	The user's first name
last_name	The user's last name
cell_num	The user's mobile phone number
profile	The user's title, company, and any custom attributes as an array. Note: when updating a custom attribute, either the "id" or "name" of the custom attribute is required. `{ "profile" : { "title" : "Sr Demand Gen Manager", "company" : "CORPS", "custom_attributes" : [ { "id" : "custom_attribute_id", "name" : "custom_attribute_name", "value":"custom_attribute_value" } ] } }`
manager_id	Either the unique numerical id assigned to the manager in WorkBoard, or the manager's email address. (The manager must have an existing WorkBoard account)

# Sample Request
curl -g -X POST  -H "Authorization: Bearer {access_token}" https://www.myworkboard.com/wb/apis/user/?first_name=Lynne&last_name=Smith&email=lynnesmith@kikasco.com&manager_id=34&profile[title]=CTO&company=Kikasco

# Sample Response
{
   "success":true,
   "message":"",
   "data":
      {
      "totalCount":1,
      "user":
         {
         "user_id":"105379",
         "user_name":"",
         "email":"lynnesmith@kikasco.com",
         "first_name":"Lynne",
         "last_name":"Smith",
         "wb_email":"lynnesmith",
         "cell_num":null,
         "create_at":1508436848,
         "last_visited_at":"1508436848",
         "picture":"https:\/\/files-workboard-prod.s3.amazonaws.com\/LetterImages\/Letters_L.png",
         "time_zone":null,
         "profile":
            {
            "title":"CTO",
            "company":"Kikasco"
            }
         }
      }
}

Update user profile

PUT  /user/{user_id}

Modify a user's profile information, including first name, last name, company, title, cell phone, or direct reporting manager. If the user_id parameter is not included, the updates will be applied to the current authenticated user. Include the user attributes you wish to update as parameters in your API call.

(Note: Authorized users can also use an API request to update a user's WorkBoard administration role. Please contact us to request details.

Parameters
user_id	Read Only. The value can be either the unique numerical id assigned to each user in WorkBoard, or the user's email address. If this parameter is not included, profile updates will be applied to the current authenticated user.
email	The user's email address
first_name	The user's first name
last_name	The user's last name
cell_num	The user's mobile phone number
picture	A publicly accessible URL for the user's profile picture (must start with http or https)
status	To re-enable the user, set this value to "active". A valid email address must be passed in the email attribute.
profile	The user's title, company, and any custom attributes as an array. Note: when updating a custom attribute, either the "id" or "name" of the custom attribute is required. `{ "profile" : { "title" : "Sr Demand Gen Manager", "company" : "CORPS", "custom_attributes" : [ { "id" : "custom_attribute_id", "name" : "custom_attribute_name", "value":"custom_attribute_value" } ] } }`
time_zone	Update a user's timezone by passing a valid timezone string in your request.
manager_id	Either the unique numerical id assigned to the manager in WorkBoard, or the manager's email address. (The manager must have an existing WorkBoard account). Note: You must provide the org_role if you are passing the manager_id in your request.
org_role	(Required if you pass manager_id in your request) The reporting relationship between the user and the manager. Permitted values are "dotted" and "direct".
org_role_action	Remove a dotted line reporting relationship by setting this parameter to "remove."

# Sample Request
curl -g -X PUT  -H "Authorization: Bearer {access_token}" https://www.myworkboard.com/wb/apis/user/?profile[title]=CMO&user_id={user_id}

# Sample Response
{
    "success"   : true,
    "message"  :  "",
    "data"   :  [
       "totalCount" : "1",
       "user" : {
           "user_id": "76",
           "username": "kanet@kikasco.com",
           "email": "kanet@kikasco.com",
           "first_name": "Kanet",
           "last_name": "True",
           "wb_email": "kanet@myworkboard.com",
           "cell_num": null,
           "create_at": 1441297537,
           "lastvisit_at": "1441331869",
           "picture": "https://myworkboard.com/wb/images/profile/LetterImages/Letters_T.png",
           "time_zone": "America/Los_Angeles",
           "theme": null,
           "profile": {
              "title": "CMO",
              "company": "Kikasco"
           }
       }
    ]
}

Delete user

PATCH  /user/{user_id}

Delete a user's account and remove them from the organization. A successful request will return a 204 code.

Parameters
action	Required. Disable the user's access. Permitted value is "disable" Note: If this parameter is missing, WorkBoard will respond with an error message.
user_id	The value can be either the unique numerical id assigned to each user in WorkBoard, or the user's email address.

# Sample Request
curl -g -X PATCH  -H "Authorization: Bearer {access_token}" https://www.myworkboard.com/wb/apis/user/?user_id={user_id}&action=disable

# Successful Response
204 no content

Get user goals

GET  /user/{user_id}/goal/{goal_id}

List details for goals belonging to the user. Unless a specific goal_id is specified, the list will include all open and closed goals that the user owns, contributes to or has responsibility for updating.

Parameters
user_id	Optional. The unique numerical id assigned to each user in WorkBoard. If this parameter is not included, the response will include profile data for the current authenticated user.
goal_id	Optional. The unique numerical id assigned to each goal in WorkBoard. If you include this parameter in your request, the response will include only data for the specified goal; otherwise, it will include all goals belonging to the user. Note: the currently authenticated user must have permission to view the goals.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/user/goal"


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "user": {
      "user_id": "30893",
      "user_name": "",
      "email": "jack.ceomack@kikasco.com",
      "first_name": "Jack",
      "last_name": "Ceomack",
      "wb_email": "jack.ceomack",
      "cell_num": "",
      "create_at": 1427704438,
      "last_visited_at": "1473362458",
      "picture": "https://files-workboard-prod.s3.amazonaws.com/318fe8aeb1393540ec4afe4b1b978ced3ace5077/original/?AWSAccessKeyId=AKIAIZKBP47N5BLR422A&Expires=1475966170&Signature=SryXUAHYH7Dmm%2B7kbc8NUT20fTo%3D",
      "time_zone": "America/Los_Angeles",
      "profile": {
        "title": "CEO",
        "company": "Kikasko"
      },
      "goal": {
        "0": {
          "goal_id": "14979",
          "goal_name": "Bring our A game and operate as a world class team",
          "goal_owner": "30893",
          "goal_create_at": "1470871083",
          "goal_start_date": "1467331200",
          "goal_target_date": "1483142400",
          "goal_progress": "37",
          "goal_progress_color": "#b7b7b7",
          "goal_status": "1",
          "goal_owner_full_name": "Jack",
          "goal_team_id": "13348",
          "goal_team_name": "eStaff",
          "goal_metrics": [
            {
              "metric_id": "25051",
              "metric_name": "Full transparency on goals and execution status ",
              "metric_initial_data": "10",
              "metric_target": "100",
              "metric_progress": "10",
              "metric_progress_color": "#b7b7b7",
              "metric_last_update": "1472774400",
              "metric_next_update": "1473379200",
              "metric_source_from": "Kyle Rayner"
            },
            {
             ...
            }
          ]
        },
        "1": {
        ...
        },
        "goals_count": 2
      },
      "goal_count": 2
    }
  }
}

Get user teams

GET  /user/{user_id}/team/{team_id}

List all the teams that the user manages, or of which they are a member.

Parameters
user_id	Optional. The unique numerical id assigned to each user in WorkBoard. If this parameter is not included, the response will include profile data for the current authenticated user.
team_id	Optional. The unique numerical id assigned to each team in WorkBoard. If you include this parameter in your request, the response will include only data for the specified team; otherwise, it will include all teams to which the user belongs.

# Sample Request
curl -g -X GET -H "Authorization: Bearer {access_token}" https://www.myworkboard.com/wb/apis/user/team

# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "user": {
      "user_id": "30893",
      "user_name": "",
      "email": "jack.ceomack@kikasco.com"
      "first_name": "Jack",
      "last_name": "Ceomack",
      "wb_email": "jack.ceomack",
      "cell_num": "",
      "create_at": 1427704438,
      "last_visited_at": "1473375087",
      "picture": "https://files-workboard-prod.s3.amazonaws.com/318fe8aeb1393540ec4afe4b1b978ced3ace5077/original/?AWSAccessKeyId=AKIAIZKBP47N5BLR422A&Expires=1475968311&Signature=J6Dz2QBQHWa737swi%2B2Oks%2FXM%2F8%3D",
      "time_zone": "America/Los_Angeles",
      "profile": {
        "title": "CEO",
        "company": "Kikasko"
      },
      "team": [
        {
          "team_id": "71619",
          "team_name": "eStaff",
          "team_role": "1",
          "team_role_name": "Manager",
          "team_owner": "30893",
          "is_team_owner": true
        },
        {
          "team_id": "13350",
          "team_name": "Marketing",
          "team_role": "2",
          "team_role_name": "Member",
          "team_owner": "30895",
          "is_team_owner": false
        },
        {
          ...
        }
      ],
      "team_count": 8
    }
  }
}

Bulk User Provisioning

PUT  /user/importOrg

Add, update and modify users in the existing organization. You will need to have the org_id for your organization and the data admin role in WorkBoard in order to use this API.

Note: When updating an existing user, the email property in the user object is the key used to identify the user.

Parameters
org_id	Required. The unique numerical id assigned to each organization in WorkBoard. (Get the org_id with the user resource — don't specify a user_id in your request)
org_members	The users to add or update, passed as an array: first_name: the user's first name last_name: the user's last name email: the user's email address title: the user's title action: the action to take. Permitted values are "add" and "deactivate." The deactivate operation with this endpoint will also remove any team membership/assignment, any managerial reporting, any recurring AIs, and any person goals. If you would prefer to disable the user without these data changes, use `DELETE /wb/apis/user/{user_id}` direct_manager: Optional. the email address of the user's direct manager

Parameters

org_id

Required. The unique numerical id assigned to each organization in WorkBoard. (Get the org_id with the user resource — don't specify a user_id in your request)

org_members

The users to add or update, passed as an array:
first_name: the user's first name
last_name: the user's last name
email: the user's email address
title: the user's title
action: the action to take. Permitted values are "add" and "deactivate." The deactivate operation with this endpoint will also remove any team membership/assignment, any managerial reporting, any recurring AIs, and any person goals. If you would prefer to disable the user without these data changes, use `DELETE /wb/apis/user/{user_id}`
direct_manager: Optional. the email address of the user's direct manager

Currently, the API doesn't enforce the upper limit on the org_members. We recommend you limit the size to maximum 25 users to avoid timeouts.

# Sample Payload
{  
  "org_id":"123",
  "org_members":[  
    {  
      "first_name":"Celena",
      "last_name":"Siri",
      "email":"wobo-celena@someorg.com",
      "title":"Manager",
      "action":"add"
    },
    {  
      "first_name":"John",
      "last_name":"Cena",
      "email":"wobo-john@someorg.com",
      "title":"Member",
      "action":"add",
      "direct_manager":"wobo-celena@someorg.com"
    }
  ]
}

Goals

The Goal resource represents a team or personal goal set in WorkBoard. Goals belong to teams or individuals. Depending on the permissions set by the goal owner, the goal may be accessible to all or a subset of individuals within a team or organization. Note that for all API requests to the Goal resource, the authenticated user must have permission to view the goal.

Use the Goal resource to request goal and metric data from WorkBoard, either by user or by goal.

Resource URL : https://www.myworkboard.com/wb/apis/goal

The following attributes are associated with the Goal resource:

Attribute	Description
goal_name	The name of your goal.
goal_id	Read Only. The unique numerical id assigned to each goal in WorkBoard
goal_owner_id	The goal owner's user id. The user id is a unique numerical id assigned to each user in WorkBoard.
goal_narrative	A short description or additional details about the goal.
goal_create_at	Read Only. The date on which the goal was created, in Unix timestamp format (in seconds)
goal_start_date	The start date set for the goal, in Unix timestamp format (in seconds)
goal_target_date	The target completion date set for the goal, in Unix timestamp format (in seconds)
goal_progress	Read Only. The progress towards goal completion, calculated as a percentage
goal_progress_color	Read Only. The progress towards goal completion, represented as a RAG rating (red, amber, or green)
goal_status	The current status of the goal (either "Active" or "Closed")
goal_owner_full_name	The full name of the goal owner
goal_team_id	The unique numerical id assigned to the team that owns the goal
goal_team_name	The name of the team that owns the goal
goal_metrics	List of metrics tied to the goal (returned as an array)
goal_metrics_count	Total number of metrics tied to the goal
goal_comments	Text of all comments associated with the goal (returned as an array)
goal_comments_count	Read Only. Total number of comments associated with the goal
created_by	Read Only. The unique numerical id of the user who created the goal (Note: initial value is set to goal_owner_id for any goal created before May 20, 2019)
updated_by	Read Only. The unique numerical id of the user who last updated the goal (Note: initial value is set to goal_owner_id for any goal last updated before May 20, 2019)
modified_at	Read Only. Date of the last update as a UNIX timestamp (Note: initial value is set to goal_create_at for any goal last updated before May 20, 2019)

Get goals

GET  /goal/{goal_id}

List all goals the user owns, and those to which they contribute.

Parameters
goal_id	Optional The unique numerical id assigned to each goal in WorkBoard. Include this parameter to return attributes of the specified goal only; otherwise all goals will be returned.
goal_owner_id	Either the unique user id or email address belonging to the goal owner. Include this parameter to return all goals belonging to the specified owner. (Note, if both goal_owner_id and goal_id parameters are include in the request, goal_owner_id will be ignored.)
team_owner_id	Either the unique user id or email address belonging to the team owner. Include this parameter to return all goals belonging to the specified team owner. (Note, if both team_owner_id and team_id parameters are include in the request, team_owner_id will be ignored.)
team_id	The unique numerical id assigned to each team in WorkBoard. Include this parameter to return goals belonging to the specified team.
goal_status	The current state of the goal; permitted values are “1” (active) or “2” (closed). If you want both closed and active goals, then set goal_status to the comma separated values: “1,2”
offset	Specify the starting point for the results returned. Permitted values are integers greater than or equal to 0. The default value is 0.
limit	The number of goals returned per page. Permitted values are integers greater than or equal to 0. The default value is 15.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://myworkboard.com/wb/apis/goal"


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 27,
    "goal": {
      "0": {
        "goal_id": "14979",
        "goal_name": "Bring our A game and operate as a world class team",
        "goal_owner": "30893",
        "goal_create_at": "1470871083",
        "goal_start_date": "1467331200",
        "goal_target_date": "1483142400",
        "goal_progress": "37",
        "goal_progress_color": "#b7b7b7",
        "goal_status": "1",
        "goal_owner_full_name": "Jack",
        "goal_team_id": "13348",
        "goal_team_name": "eStaff",
        "goal_metrics": [
          {
            "metric_id": "25051",
            "metric_name": "Full transparency on goals and execution status ",
            "metric_initial_data": "10",
            "metric_target": "100",
            "metric_progress": "10",
            "metric_progress_color": "#b7b7b7",
            "metric_last_update": "1472774400",
            "metric_next_update": "1473379200",
            "metric_source_from": "Kyle Rayner"
          },
          {
            ...
          }
        ]
      },
      "1": {
        ...
      },
      "goals_count": 26
    }
  }
}

Create a goal

POST  /goal/

Create a goal for a user in your organization, including metrics sourced from the same person. Make sure you have data admin permission for your access token.

Goal JSON Attributes
goal_name	Required The name of your goal.
goal_narrative	Optional A description or narrative for your goal.
goal_owner	Either the unique user id or email address belonging to the goal owner.
goal_type	The goal type. Permitted values are "1" (Team goal) or "2" (Personal goal).
goal_start_date	The start date for the goal as a valid date string.
goal_target_date	The end date for the goal as a valid date string (must be later than the goal_start_date).
goal_permission	Comma-separated list of view permissions for the goal. Permitted values for team goals are "team", "report", "internal", "any". Permitted values for personal goals are "owner", "manager", "internal".
goal_team	An array of team_id or team_name that your team members have created in the organization
goal_category	An array of category_id or category_name that your team members have created in the organization
goal_metrics	An array of goal metrics, formatted as an array.

Metric JSON Attributes
metric_name	Required The name of your metric.
metric_owner	Either the unique user id or email address belonging to the goal owner.
metric_source_from	The source of the metric. Currently, the only permitted value is "1".
metric_update_interval	The update interval for the metric. Permitted values "1" (daily), "2" (weekly), "3" (monthly), "4" (quarterly).
metric_counting_type	The relationship between the starting value and the target. Permitted values "1" (counting up), "2" (counting down), "3" (exact to target).
metric_progress_type	The progress calculation type. Permitted values "1" (last update), "2" (total), "3" (average).
metric_initial_data	The starting value for the metric.
metric_target	The target value for the metric.
metric_unit	The data type for your metric. Permitted values "1" (number), "2" (currency), "3" (percentage).
metric_permission	Optional Comma-separated list of view permissions for the metric. Permitted values for team goals are "team", "report", "internal", "any". Permitted values for personal goals are "owner", "manager", "internal". (If this parameter is not included in your request, it will automatically be set to the values in goal_permission

# Sample JSON Payload
{
  "goals" : [
    {
      "goal_name" : "Goal Name",
      "goal_narrative" : "Goal narration", 
      "goal_owner" : "16391",
      "goal_type" : "Goal Type", 
      "goal_start_date" : "Valid Date String", 
      "goal_target_date" : "Valid Date String",
      "goal_permission" : "Goal permission, separated by comma",
      "goal_team" : [{"id": team_id}],
      "goal_category" : [{"id": cat_id}],
      "goal_metrics" : [
        {
          "metric_name" : "Metric Name",
          "metric_source_from" : "Source From Type",
          "metric_update_interval" : "Interval Type",
          "metric_counting_type" : "Counting Type",
          "metric_progress_type" : "Progress Type",
          "metric_initial_data" : "Initial Data",
          "metric_target" : "Target",
          "metric_unit" : "Unit Type",
          "metric_permission" : "Metric permission separated by comma"
        }    
      ]
    }    
  ]
}







# Sample Response

{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 27,
    "goal": {
      "0": {
        "goal_id": "14979",
        "goal_name": "Bring our A game and operate as a world class team",
        "goal_owner": "30893",
        "goal_create_at": "1470871083",
        "goal_start_date": "1467331200",
        "goal_target_date": "1483142400",
        "goal_progress": "37",
        "goal_progress_color": "#b7b7b7",
        "goal_status": "1",
        "goal_owner_full_name": "Jack",
        "goal_team_id": "13348",
        "goal_team_name": "eStaff",
        "goal_metrics": [
          {
            "metric_id": "25051",
            "metric_name": "Full transparency on goals and execution status ",
            "metric_initial_data": "10",
            "metric_target": "100",
            "metric_progress": "10",
            "metric_progress_color": "#b7b7b7",
            "metric_last_update": "1472774400",
            "metric_next_update": "1473379200",
            "metric_source_from": "Kyle Rayner"
          },
          {
            ...
          }
        ]
      },
      "1": {
        ...
      },
      "goals_count": 26
    }
  }
}

Get a goal's metric

GET  /goal/{goal_id}/metric/{metric_id}

List data for one metric (specified by the metric_id parameter) associated with the goal specified by the goal_id parameter.

Parameters
goal_id	The unique numerical id assigned to each goal in WorkBoard.
metric_id	The unique numerical id assigned to each metric in WorkBoard.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://myworkboard.com/wb/apis/goal/{goal_id}/metric/{metric_id}"


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "goal": {
      "goal_id": "14977",
      "goal_name": "Be the market & product innovation leader",
      "goal_owner": "30893",
      "goal_create_at": "1470870817",
      "goal_start_date": "1467331200",
      "goal_target_date": "1483142400",
      "goal_progress": "42",
      "goal_progress_color": "#b7b7b7",
      "goal_status": "1",
      "goal_owner_full_name": "Me",
      "goal_team_id": "13348",
      "goal_team_name": "eStaff",
      "goal_metrics": [
        {
          "metric_id": "25046",
          "metric_name": "k2 launch goes according to plan",
          "metric_initial_data": null,
          "metric_target": "14",
          "metric_progress": "43",
          "metric_progress_color": "#b7b7b7",
          "metric_last_update": "1473206400",
          "metric_next_update": "1473292800",
          "metric_source_from": "Product Launch"
        }
      ],
      "goal_metrics_count": 4,
      "goal_comments": [
        {
          ...
        }
      ],
      "goal_comments_count": 1
    }
  }
}

Get a goal's alignment

GET  /goal/{goal_id}/alignment

List aligned and dependent goals associated with the goal specified by the goal_id parameter. Note, the logged in user must be have data-admin permission in order to view the goal alignment.

Parameters
goal_id	The unique numerical id assigned to each goal in WorkBoard.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://myworkboard.com/wb/apis/goal/{goal_id}/alignment"


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "alignment": [
      {
        "goal_id": "1004",
        "goal_name": "CX: Engage and enable customers to achieve better business results",
        "goal_owner": "Drake Johnson",
        "goal_team_name": "Agile development learning",
        "goal_target_date": "Aug 31, 2018",
        "goal_progress": "0%",
        "goal_progress_color": "#db3a1b",
        "goal_alignments": [
          {
            "goal_id": "906",
            "goal_name": "AMEXATSP011617M: Set the bar on innovation with key apps and move to the front of the pack",
            "goal_owner": "Drake Johnson",
            "goal_team_name": "",
            "goal_target_date": "Mar 01, 2018",
            "goal_progress": "2%",
            "goal_progress_color": "#db3a1b",
            "goal_alignments": []
          }
        ]
      },
      {
        "goal_id": "720",
        "goal_name": "100% Assets driven sales",
        "goal_owner": "John Legend",
        "goal_team_name": "",
        "goal_target_date": "Nov 30, 2016",
        "goal_progress": "45%",
        "goal_progress_color": "#db3a1b",
        "goal_alignments": [
          {
            "goal_id": "906",
            "goal_name": "AMEXATSP011617M: Set the bar on innovation with key apps and move to the front of the pack",
            "goal_owner": "Drake Johnson",
            "goal_team_name": "",
            "goal_target_date": "Mar 01, 2018",
            "goal_progress": "2%",
            "goal_progress_color": "#db3a1b",
            "goal_alignments": []
          },
          {
            "goal_id": "945",
            "goal_name": "Application Development Objective-1",
            "goal_owner": "Drake Johnson",
            "goal_team_name": "Application & Development Team",
            "goal_target_date": "Mar 31, 2018",
            "goal_progress": "0%",
            "goal_progress_color": "#db3a1b",
            "goal_alignments": [
              {
                "goal_id": "1116",
                "goal_name": "OKR -WS - 1",
                "goal_owner": "Drake Johnson",
                "goal_team_name": "team - 5",
                "goal_target_date": "Apr 30, 2019",
                "goal_progress": "67%",
                "goal_progress_color": "#99cc66",
                "goal_alignments": []
              }
            ]
          }
        ]
      }
    ]
  }
}

Metric

The Metric resource represents a metric or key result in WorkBoard. Metrics belong to individual or team goals. Depending on the permissions set by the goal owner, the metric data may be accessible to all or a subset of individuals within a team or organization. Note that for all API requests to the Metric resource, the authenticated user must have permission to view the metric.

Use the Metric resource to query, create and update metrics for WorkBoard goals.

Resource URL : https://www.myworkboard.com/wb/apis/metric

The following attributes are associated with the Metric resource:

Attribute	Description
metric_id	Read Only. The unique numerical id assigned to each metric
metric_goal_id	Read Only. The unique numerical id assigned to the goal with which the metric is associated
metric_owner	Either the unique user id or email address belonging to the metric owner.
metric_name	The name of the metric
metric_initial_data	The starting value for the metric, as set during goal creation
metric_target	The target value for the metric
metric_progress	Read Only. Progress towards the target metric value, calculated as a percentage
metric_progress_color	Read Only. Progress towards the target metric value, represented as a RAG rating (red, amber or green)
metric_create_at	Read Only. The date on which the metric was created, in Unix timestamp format (in seconds)
metric_last_update	Read Only. The date on which the metric was last updated, in Unix timestamp format (in seconds)
metric_next_update	Read Only. The date on which the metric is next due to be updated, in Unix timestamp format (in seconds)
metric_last_data	The value from the latest metric update
metric_source_from	The source for metric data updates. Possible values are: "1" - An individual user "2" - Progress on a workstream "3" - Another WorkBoard metric "4" - A workstream's cycle time "5" - A multi-user survey "6" - Rolled up from other goals
metric_interval	The scheduled frequency for metric updates. Possible values are: "1" - Daily "2" - Weekly "3" - Monthly "4" - Quarterly
metric_counting_type	The relationship between the starting value and the target. Possible values are: "1" - The metric counts up to a target value "2" - The metric counts down to a target value "3" - The metric counts up or down to an exact value (Threshold) "4" - The metric If metric is counted with a range "5" - If metric is counted with a survey "6" - If metric is counted with a range
metric_status	The current state of the metric. Possible values are: "1" - Active "2" - Closed
created_by	Read Only. The unique numerical id of the user who created the metric (Note: initial value is set to metric_owner for any metric created before May 20, 2019)
updated_by	Read Only. The unique numerical id of the user who last updated the goal or metric (Note: initial value is set to metric_owner for any metric last updated before May 20, 2019)
modified_at	Read Only. Date of the last update as a UNIX timestamp (Note: initial value is set to metric_create_at for any metric last updated before May 20, 2019)

The Metric resource includes a dependent resource, MetricData, which represents the data from periodic metric updates. The MetricData resource has the following attributes:

Attribute	Description
metric_data_id	Read Only. The unique numerical id assigned to each metric data update.
metric_data_value	The value of an individual metric data update.
metric_data_created_by	Read Only. The user id of the individual that updated the metric
metric_data_created_at	Read Only. The date when the metric data was added, in Unix timestamp format
metric_data_updated_at	Read Only. The date when the metric data was last updated, in Unix timestamp format
metric_data_comment	User comments associated with the metric data update

Get all metrics

GET  /metric/

Returns all metrics that the authenticated user is responsible for updating.

Parameters
metric_id	The unique numerical id assigned to each metric in WorkBoard. Include the metric_id parameter in the request to limit the response to a specific metric.
goal_owner_id	Either the unique user id or email address belonging to the goal owner. Include this parameter to return all goals belonging to the specified owner. (Note, if both goal_owner_id and goal_id parameters are include in the request, goal_owner_id will be ignored.)
goal_id	The unique numerical id assigned to each goal in WorkBoard. Include this parameter to return metrics from the specified goal only.
include_metric_data	Include this parameter to indicate whether to include metric data for charts the response. Possible values are "no" (default) or "yes"

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/metric"

# or
curl -g -X GET "https://www.myworkboard.com/wb/apis/metric/token={access_token}"

# Sample Response
{
  "success"   : true,
  "message"  :  "",
  "data"   :  [
    "totalCount" : "25",
    "metric" : [
      {
        "metric_id": "{metric_id}",
        "metric_name" : "Metric name",
        "metric_initial_data" : "Metric initial  data",
        "metric_target" : "Metric target value",
        "metric_achieve_target" : "Metric current achieved target",
        "metric_owner_id" : "{user_id}",
        "metric_progress" : "Metric progress",
        "metric_progress_color" :"Metric progress color",
        "metric_last_update" : "1438214400",
        "metric_next_update" : "1438300800",
        "metric_source_from" : "1",
        "metric_counting" : "1",
        "metric_interval" : "2",
        "metric_status" : "1"
      },
      {
        …
      }
    ]
  ]
}

Get one metric (current user)

GET  /metric/{metric_id}

Returns data for an individual metric.

Parameters
metric_id	The unique numerical id assigned to each metric in WorkBoard. Include the metric_id parameter in the request to limit the response to a specific metric.
goal_owner_id	Either the unique user id or email address belonging to the goal owner. Include this parameter to return all goals belonging to the specified owner. (Note, if both goal_owner_id and goal_id parameters are include in the request, goal_owner_id will be ignored.)
goal_id	The unique numerical id assigned to each goal in WorkBoard. Include this parameter to return metrics from the specified goal only.
include_metric_data	Include this parameter to indicate whether to include metric data in the response or not. Possible values: "no" (default) or "yes"

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/metric/{metric_id}"

# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "metric": {
      "metric_id": "25052",
      "metric_goal_id": "14979",
      "metric_name": "Simplify 3 primary processes in sales, contracts, finance and HR",
      "metric_initial_data": "0",
      "metric_target": "12",
      "metric_progress": "0",
      "metric_progress_color": "#b7b7b7",
      "metric_last_update": "1469923200",
      "metric_next_update": "1475193600",
      "metric_source_from": "1",
      "metric_achieve_target": 0
    }
  }
}

Add metric data

PUT  /metric/{metric_id}

Update the value of an individual metric, including name, starting value, target value, and current value. If you do not include the metric_data_id parameter, the value will be applied to the most recent update date according to the metric update frequency set in WorkBoard.

Parameters
metric_id	Read Only. The unique numerical id assigned to each metric
metric_data	The value you want to use to update the metric.
metric_data_id	The unique numerical id assigned to each metric update value. If you do not include this parameter, the value passed in the metric_data parameter will be applied to the most recent update date according to the metric update frequency set in WorkBoard.
metric_comment	Include this parameter to add a comment to this metric data update.

# Sample Request
curl -X PUT -d
"token={access_token}&metric_data={metric_data}&metric_data_id={metric_data_id}&metric_comment={metric_comment}" https://www.myworkboard.com/wb/apis/metric/{metric_id}

# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "metric": {
      "metric_id": "25052",
      "metric_goal_id": "14979",
      "metric_name": "Simplify 3 primary processes in sales, contracts, finance and HR",
      "metric_initial_data": "0",
      "metric_target": "12",
      "metric_progress": "17",
      "metric_progress_color": "#b7b7b7",
      "metric_last_update": "1469923200",
      "metric_next_update": "1475193600",
      "metric_source_from": "1",
      "metric_achieve_target": "2"
    }
  }
}

Get a metric's tags

GET  /apis/metric/{metric_id}/tags

Returns all key result tags mapped to the given metric in the system.

Parameters
metric_id	The unique numerical id assigned to each metric in WorkBoard. Include the metric_id parameter in the request to get all tags mapped to the metric.

# Sample Response
{
	"success": true,
	"message": "",
	"data": {
		"totalCount": 3,
        "tags": [
            {
                "id": 4,
                "name": "tag 4",
                "status": 1,
                "group_id": 1,
                "group_name": "Other",
                "group_status": 1,
                "updated_by": 26517,
                "updated_date": "2021-09-22 08:50:00"
            },
            {
    ...
            }
        ]
    }
}

Get a list of metrics' tags

GET /apis/metric/krtags?metric_ids=metric_id1,metric_id2

Returns all tags mapped to given metric list.

Parameters
metric_ids	Comma separated metric id values , include the metric_ids parameter in the request to get all tags mapped to the metric list.

# Sample Response
{
    "success": true,
    "message": "",
    "data": {
        "totalCount": 2,
        "metrics": [
            {
                "id": 10266,
                "name": "“02. FY'21 - KR",
                "tags": [
                    {
                        "id": 60,
                        "name": "grp1-tag1",
                        "status": 1,
                        "group_id": 4,
                        "group_name": "group 1",
                        "group_status": 1,
                        "updated_by": 26517,
                        "updated_date": "2021-09-23 07:54:30"
                    },                 
                    {
                        "id": 67,
                        "name": "Kr-tag-2",
                        "status": 1,
                        "group_id": 5,
                        "group_name": "KR Tagging",
                        "group_status": 1,
                        "updated_by": 26517,
                        "updated_date": "2021-09-23 13:35:45"
                    },
                    {
                        "id": 68,
                        "name": "Kr-tag-3",
                        "status": 1,
                        "group_id": 5,
                        "group_name": "KR Tagging",
                        "group_status": 1,
                        "updated_by": 26517,
                        "updated_date": "2021-09-23 13:35:45"
                    },
                    {
                        "id": 3,
                        "name": "tag-3",
                        "status": 1,
                        "group_id": 1,
                        "group_name": "Other",
                        "group_status": 1,
                        "updated_by": 26517,
                        "updated_date": "2021-09-22 08:27:16"
                    }
                ]
            },
            {
                "id": 10261,
                "name": "MiT - KR - FY 20-21",
                "tags": [
                    {
                        "id": 3,
                        "name": "tag-3",
                        "status": 1,
                        "group_id": 1,
                        "group_name": "Other",
                        "group_status": 1,
                        "updated_by": 26517,
                        "updated_date": "2021-09-22 08:27:16"
                    },
                    {
                        "id": 5,
                        "name": "tag-5",
                        "status": 1,
                        "group_id": 1,
                        "group_name": "Other",
                        "group_status": 1,
                        "updated_by": 26517,
                        "updated_date": "2021-09-22 08:27:16"
                    }
                ]
            }
        ]
    }
}

Get all metrics mapped to a tag

GET /apis/metric/tags?tag_id={tag_id}

Returns all metrics mapped to the given tag_id.

Parameters
tag_id	A unique numerical id assigned to each tag, which returns all metrics mapped to that tag.
limit	The number of metrics returned per page. Permitted values are integers greater than or equal to 0. The default value is 50.
offset	Specify the starting point for the results returned. Permitted values are integers greater than or equal to 0. The default value is 0.

# Sample Response
{
    "success": true,
    "message": "",
    "data": {
        "totalCount": 2,
        "metrics": [
            {
                "id": 10261,
                "name": "Test KR",
                "status": 1,
                "updated_by": 26517,
                "updated_date": "2021-09-22 08:36:03"
            },
            {
                "id": 10266,
                "name": "Test KR 2",
                "status": 1,
                "updated_by": 26517,
                "updated_date": "2021-09-22 14:20:22"
            }
        ]
    }
}

Add tags to a single metric

PUT apis/metric/{metric_id}/tags

Add multiple tags to the given metric.

Parameters
tag_ids	Array list of tag ids.

Notes:

Maximum tag list allowed is 50 per request
Only valid tags will be considered

Example Input
{
    "tag_ids": [1,2,3,4,5]
}


# Sample Success Response
{
    "status": "success",
    "message": "Successfully mapped tags to metric"
}

# Sample Error Response (with invalid tags)
{
    "status": "error",
    "message": "Given tags are not valid"
}

# Sample Error Response (when tag limit exceed)
{
    "status": "error",
    "message": "Max tags allowed per request is 50"
}

Add tags to multiple metrics

POST /apis/metric/tags

Add multiple tags to multiple metrics.

Parameters
metrics	JSON list of metric_id & tag_ids.

Notes:

Maximum tag list allowed is 50 per request
Only valid tags will be considered

# Example Input
{
   "metrics":[
      {
         "metric_id"  :  "metric_id1",
         "tag_ids"  :  [
            "tag_id1",  "tag_id2",  "etc"
             ]
      },
      {
         "metric_id"  : "metric_id2",
         "tag_ids" :   [
              "tag_id3",  "tag_id4", "etc"
]
      },  {...}
   ]
}


# Sample Success Response
{
    "status": "success",
    "message": {
        "added": "Successfully tags are mapped for the metrics `10266, 10261`",        
            }
}

# Sample Error Response
{
    "status":  "error",
    "message":   {
        "permissionDenied":  "You don't have access to add a tag for the metrics `110266, 101265, 102161`",
        "tagLimitExceeds":  "Max tags allowed per request is 50, `10260` metrics exceeds the limit"
    }
}

Remove a metric's tags

DELETE /apis/metric/{metric_id}/tags

Delete given tag lists mapped to the metric.

Parameters
tag_ids	Array list of tag ids.

# Example Input
{
" tag_ids" : ["tag_id1", "tag_id2", etc]
}

# Sample Success Response
{
    "status": "success",
    "message": "Successfully removed tags from the KR"
}

# Sample Error Response (with invalid access)
{
    "status": "error",
    "message": "You don't have access to delete a tag from this KR"
}

# Sample Error Response (with invalid tags)
{
    "status": "error",
    "message": "Given tags are not valid."
}

Attribute	Description
tags_id	Read Only. The unique numerical id assigned to each tag.
tags_name	The name of the tag.
tags_status	1 for Active, 2 archived. Include the status parameter in the request to limit the response of tags with a particular status
tags_group_id	Read Only. The unique numerical id assigned to each grouping of tags created.
tags_group_name	The name of the group of tags created.
tags_group_status	1 for Active, 2 archived. Include the group_status parameter in the request to limit the response of tags with a particular status.

Parameters
tag_id	Optional. A unique numerical id assigned to each tag. Include this parameter to return attributes of the specified tag only; otherwise all tags will be returned.
status	1 for Active, 2 archived. Include the status parameter in the request to limit the response of tags with a particular status.
group_id	A numeric value for filtering tags available in the specific Tag group.
limit	The number of tags returned per page. Permitted values are integers greater than or equal to 0. The default value is 50.
offset	Specify the starting point for the results returned. Permitted values are integers greater than or equal to 0. The default value is 0.

Parameters
tag_id	Required. A unique numerical id assigned to each tag. Include this parameter to return attributes of the specified tag only; otherwise all tags will be returned.

Parameters
tag_id	Optional. A unique numerical id assigned to each tag. Include this parameter to return attributes of the specified tag only; otherwise all tags will be returned.
status	1 for Active, 2 archived. Include the status parameter in the request to limit the response of tags with a particular status.
group_id	A numeric value for filtering tags available in the specific Tag group.
limit	The number of tags returned per page. Permitted values are integers greater than or equal to 0. The default value is 50.
offset	Specify the starting point for the results returned. Permitted values are integers greater than or equal to 0. The default value is 0.

Parameters
tag_ids	Array list of tag ids

Parameters
metrics	JSON list of metric_id & tag_ids

Parameters
tag_ids	Array list of tag ids

Action Item

The Action Item resource represents action items (activities) in WorkBoard. Action items can also include subactions, comments and files.

Note that for all API requests to the Action Item resource, the authenticated user must have permission to view the action items.

Use the Action Item resource to query, create, delete or update WorkBoard action items.

Resource URL : https://www.myworkboard.com/wb/apis/activity

The following attributes are associated with the Action Item resource:

Attribute	Description
ai_id	Read Only - The unique numerical id assigned to each action item in WorkBoard.
ai_description	The name (or description) of the action item.
ai_note	The formatted notes associated with an action item.
ai_owner	The numerical user id of the current owner of the action item.
ai_sub_actions	Subactions associated with the action item. Each subaction includes the following nested attributes: sub_ai_id - the unique numerical id assigned to each subaction sub_ai_description - the name of the subaction sub_ai_owner - the numerical user id of the current owner of the subaction.
ai_files	Files attached to the action item. Each file contains the following nested attributes: file_id - the unique numerical id assigned to each file file_name - the file name file_url - the download URL for the file file_owner - the numerical user id of the person who uploaded the file to WorkBoard
ai_tags	Tags that have been applied to the action item. Each tag contains the following nested attributes: tag_id - the unique numerical id assigned to each tag tag_name - the name of the tag
ai_comments	All comments that have been added to the action item. Each comment contains the following nested attributes: comment - the text of the comment comment_id - the unique numerical id assigned to each comment comment_owner - the numerical user id of the person who posted the comment
ai_loop_members	All WorkBoard users who are in the loop on an action item. Each individual in the loop has the following nested attributes: user_id - the numerical WorkBoard id of the user user_email - the user's email address
ai_workstream	The unique numerical id of the workstream to which the action item belongs
ai_team	The unique numerical id of the team to which the action item belongs
ai_due_date	The action item's due date (in UNIX timestamp format)
ai_state	The current state of the action item. Possible values are: "next" "doing" "done" "pause"
ai_priority	The current priority of the action item. Possible values are: "normal" "high" "highest"
ai_rating	The current RAG rating of the action item. Possible values are: "red" "amber" "green"
ai_effort	The current effort of the action item. Possible values are: "easy" "medium" "huge"
ai_created_by	The unique numerical id of the user who created the action item
ai_due_before	The action item's original due date as set when the action item was originally created (in UNIX timestamp format)
ai_created_at	The date the action item was created (in UNIX timestamp format)
ai_completed_at	The date the action item was marked done (in UNIX timestamp format). Note, if the action item is not marked as done, this attribute will be "null."
ai_repeat_id	For recurring actions The unique numerical id assigned to each recurrance of an action item in WorkBoard.
ai_repeat_occurrence	For recurring actions The frequency at which an action item is set to recur.
ai_parent_id	For subactions The unique numerical id assigned to the subaction's parent action item.
ai_url	The action item's myworkboard.com URL.

Get Action Items

[GET] /activity/{ai_id}

List the details of existing action items. By default, this query will return the first 50 items that match your request parameters. Use the offset and limit parameters to return a different set.

Parameters
ai_id	The unique numerical id assigned to each action item in WorkBoard.
ai_owner	The numerical user id or email address of the user who currently owns the action item.
limit	Limit the number of action items that are returned in the response. If no limit is specified, the default maximum number of items returned is 50.
offset	Specify the starting point for the results returned. If no offset is specified, the default value is 0.
next_page_token	If you have made a pagination request, you will receive a next_page_token value which can be passed as a parameter in your next request.
due_date_range	Return action items with due dates in the specified range. Dates must be formatted as UTC timestamps and comma-separated: startdate,enddate
priority	Return action items with the specified priority ratings. Permitted values are: "1" (highest) "2" (high) "3" (normal)
state	Return action items with the specified state. Permitted values are: "0" (done) "1" (doing) "2" (next) "4" (pause)
rag	Return action items with the specified confidence rating. Permitted values are: "0" (green) "1" (amber) "2" (red)
effort	Return action items with the specified level of effort. Permitted values are: "1" (easy) "2" (medium) "3" (huge)
opt_filters	Limit responses based on action item properties. Only one value may be passed in this parameter (commas are not allowed). Possible values are: due_today due_this_week request_for_me work_i_delegated In_the_loop late risk

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/activity/{ai_id}"

# Sample Response
{ 
  "success":true,
  "message":"",
  "data":{ 
   "totalCount":1,
   "activity":{ 
     "ai_id":"90082",
     "ai_description":"Find out difference between Zippo and Hippo",
     "ai_created_at":"1428345606",
     "ai_state":"doing",
     "ai_rating":"red",
     "ai_priority":"medium",
     "ai_effort":"huge",
     "ai_note":"Zippo and Hippo - Hippo is heavier than Zippo\n",
     "ai_files":[ 
      { 
        "file_id":"2048",
        "file_name":"car.pdf",
        "file_url":"\/wb\/download\/file?id=MzM4NyplNmRhZTJhOTBiZTE3ODBiOWZkNzE0YThjNzRmMDIwYWZiMDZhODFh&sig=9f39d643ae66295500ca3c12da2f7352",
        "file_owner":"15513"
      }
     ],
     "ai_sub_actions":[ 
      { 
        "sub_ai_id":"95759",
        "sub_ai_description":"Who is Zippo ?",
        "sub_ai_owner":"15513"
      },
      { 
        "sub_ai_id":"95760",
        "sub_ai_description":"Who is Hippo ?",
        "sub_ai_owner":"15513"
      }
     ],
     "ai_comments":[ 
      { 
        "comment_id":"3267",
        "comment":"Anyone knows about Hippo and Zippo ?",
        "comment_owner":"15513"
      }
     ],
     "ai_due_date":"1428345606",
     "ai_workstream":"26716",
     "ai_team":"5243",
     "ai_loop_members":[ 
      { 
        "user_id":"12822",
        "user_email":"nigamg1986@gmail.com"
      }
     ],
     "ai_tags":[ 
      { 
        "tag_name":"team",
        "tag_id":"263",
   "tag_type":"2"
      },
      { 
        "tag_name":"personal",
        "tag_id":"268",
   "tag_type":"1"
      }
     ],
     "ai_due_before":"1430204400",
     "ai_owner":"15513",
     "ai_created_by":"15513",
     "ai_url":"https:\/\/wb-api2.com\/wb\/activity\/mywork?do=popup&id=90082"
   }
  }
}

Create an Action Item

[POST] /activity/

Create a new action item. Request parameters should be passed in the POST request or in the payload (as JSON).

To create an action item with a comment, sub-action, or tag, it should be passed as raw JSON, along with the ai_id either as a request parameter or in the URL.

Parameter	Description
ai_description	Required The name (or description) of the action item.
ai_note	The formatted notes associated with an action item.
ai_owner	The numerical user id of the owner of the action item.
ai_workstream	The unique numerical id of the workstream to which the action item belongs
ai_team	The unique numerical id of the team to which the action item belongs
ai_due_date	The action item's due date (in UNIX timestamp format)
ai_state	The current state of the action item. Possible values are: "next" "doing" "done" "pause"
ai_priority	The current priority of the action item. Possible values are: "normal" "high" "highest"
ai_rating	The current RAG rating of the action item. Possible values are: "red" "amber" "green"
ai_effort	The current effort of the action item. Possible values are: "easy" "medium" "huge"
ai_tags	Tags that have been applied to the action item. Each tag contains the following nested attributes: tag_id - the unique numerical id assigned to each tag tag_name - the name of the tag
ai_comments	All comments that have been added to the action item. Each comment contains the following nested attributes: comment - the text of the comment comment_id - the unique numerical id assigned to each comment comment_owner - the numerical user id of the person who posted the comment

# Sample Request
curl -g -X POST -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/activity/"

# To add a comment, sub-action, or tag, pass it as raw JSON
{
  "ai_comments": [
    {
      "comment" : "comment to be added"
    }
  ]
}

Update an Action Item

[PUT] /activity/{ai_id}/

Update an existing action item. Request parameters should be passed in the PUT request or in the payload (as JSON). Note that the ai_id parameter is required.

To update an action item with a comment, sub-action, or tag, it should be passed as raw JSON, along with the ai_id either as a request parameter or in the URL.

Parameter	Description
ai_id	Required The unique numerical id assigned to each action item in WorkBoard.
ai_description	Required The name (or description) of the action item.
ai_note	The formatted notes associated with an action item.
ai_owner	The numerical user id of the owner of the action item.
ai_workstream	The unique numerical id of the workstream to which the action item belongs
ai_team	The unique numerical id of the team to which the action item belongs
ai_due_date	The action item's due date (in UNIX timestamp format)
ai_state	The current state of the action item. Possible values are: "next" "doing" "done" "pause"
ai_priority	The current priority of the action item. Possible values are: "normal" "high" "highest"
ai_rating	The current RAG rating of the action item. Possible values are: "red" "amber" "green"
ai_effort	The current effort of the action item. Possible values are: "easy" "medium" "huge"
ai_tags	Tags that have been applied to the action item. Each tag contains the following nested attributes: tag_id - the unique numerical id assigned to each tag tag_name - the name of the tag
ai_comments	All comments that have been added to the action item. Each comment contains the following nested attributes: comment - the text of the comment comment_id - the unique numerical id assigned to each comment comment_owner - the numerical user id of the person who posted the comment

# Sample Request
curl -g -X PUT -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/activity/{ai_id}/"


# To add a comment, sub-action, or tag, pass it as raw JSON
{
  "ai_comments": [
    {
      "comment" : "comment to be added"
    }
  ]
}

Team

The Team resource represents teams in WorkBoard, including both functional teams and working groups. Note that for all API requests to the Team resource, the authenticated user must be a member of the team.

Resource URL : https://www.myworkboard.com/wb/apis/team

The following attributes are associated with the Team resource:

Attribute	Description
team_id	The unique numerical id assigned to each team in WorkBoard.
team_name	The name of the team.
team_owner	The numerical WorkBoard id of the user with the Manager role on the team.
team_type	Either a functional team or a working group.
team_role	The numerical id of the user's role on the teams to which they belong
team_role_name	The name of the user's role on the teams to which they belong (for instance, "Member," "Team Admin")
is_team_owner	Whether the user is the Manager of the team
team_workstream	Relational resource requests only All of a team's workstreams.
team_activity	Relational resource requests only All of a team's action items.
created_at	The date on which the team was created.
updated_at	The date on which the team was last updated.
external_id	A team's unique numerical id from a system other than WorkBoard.
created_from	If a team is created from a system other than WorkBoard, the source of the team as a string.

Get Teams

[GET] /team/{team_id}

List the details of teams to which the authenticated user belongs. Optionally include team_id to limit the response to details for the specified team.

Parameters
team_id	The unique numerical id assigned to each team in WorkBoard. If you do not include this parameter, the request will return all teams to which the authenticated user belongs.
role	Limit the teams returned based on whether the authenticated user is a team owner or member. Possible values: "owner", "member".
include	If the current authenticated user is an org data admin, pass this parameter with the value "org_teams" to return a dump of all organization teams.
created_at_range	Return teams with creation dates in the specified range. Dates must be formatted as UTC timestamps and comma-separated: startdate,enddate
updated_at_range	Return teams with last modified dates in the specified range. Dates must be formatted as UTC timestamps and comma-separated: startdate,enddate
offset	Specify the starting point for the results returned. Permitted values are integers greater than or equal to 0. The default value is 0.
limit	The number of teams returned per page. Permitted values are integers greater than or equal to 0. The default value is 15.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/team/{team_id}"

# Sample Response
{  
  "success":true,
  "message":"",
  "data":{  
     "totalCount":67,
     "team":[  
        {  
          "team_id":"5632",
          "team_name":"Brand 123",
          "team_role":null,
          "team_role_name":"Team Admin",
          "team_owner":15513,
          "is_team_owner":true,
          "team_type":"functional"
        },
        ...
     ]
  }
}

Create a team

[POST] /team/

Create a new functional team or working group, and add workstreams and team members.

Parameters
team_owner	Required The WorkBoard user id or email address of the user who will be the team manager.
team_name	Required The name for the team. Each team owned by an individual user must have a unique name.
team_type	The type of team. Permitted values are "functional" and "working_group". Note: if the parent_team_id parameter is not passed, the team will be created as a working group.
parent_team_id	Required for functional teams only. The id of the new team's parent in the organization's team hierarchy. If this parameter is not passed, the team will be created as a working group.
team_members	The members of the team, and their team roles, as an array: id : the user id of the member (for existing WorkBoard users only). email : the email address of the member (for new users only — they will receive an invitation to join WorkBoard). first_name : the member's first name (for new users only). last_name : the member's last name (for new users only). team_role : the member's role on the team. Permitted values are "co_manager", "exec_viewer", "team_admin", "member"
team_workstream	The workstreams or projects that should be added to the team, as an array: name : the name of the workstream type : the type of Board that should be added to the team. Permitted values are "1" (Progress Board) or "2" (Custom Agile Board)

# Sample Request
curl -g -X POST -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/team/?team_owner=94658&team_name=MarCom&team_type=working_group&team_members[0][id]=100429&team_members[0][team_role]=co_manager&team_members[1][email]=tgiana@kikasco.com&team_members[1][first_name]=Teresa&team_members[1][last_name]=Giana&team_members[1][team_role]=member&team_workstream[0][name]=Demand Generation&team_workstream[0][type]=1&team_workstream[1][name]=PR&team_workstream[1][type]=2"

# Sample JSON Payload
{
"team_owner": "94658",
"team_name": "MarCom",
"team_type" : "working_group",
"team_members" : [
    {
        "id": "100429",
        "team_role": "co_manager"
    },
    {
        "email" : "tgiana@kikasco.com",
        "first_name" : "Teresa",
        "last_name" : "Giana",
        "team_role" : "member"
    }
],
"team_workstream" : [
    {
        "name" : "Demand Generation",
        "type": "1"
    },
    {
        "name" : "PR",
        "type": "2"
    }
]
}


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 6,
    "team": {
      "team_id": "87937",
      "team_name": "MarCom",
      "team_owner": "94658",
      "team_type": "working group",
      "team_workstream": {
        "workstream_count": 2,
        "workstream": [
          {
            "ws_id": "471321",
            "ws_name": "Demand Generation",
            "ws_objective": "\n",
            "ws_status": "active",
            "ws_type": "team",
            "ws_effort": {
              "low_effort": 0,
              "medium_effort": 0,
              "large_effort": 0
            },
            "ws_pace": "STEADY",
            "ws_health": "OK",
            "ws_priority": "P5",
            "ws_progress": null,
            "ws_start_date": "1508459335",
            "ws_target_date": null,
            "ws_completion_date": null,
            "ws_team_id": "87937",
            "ws_team_name": "MarCom"
          },
          {
            "ws_id": "471322",
            "ws_name": "PR",
            "ws_objective": "\n",
            "ws_status": "active",
            "ws_type": "team",
            "ws_effort": {
              "low_effort": 0,
              "medium_effort": 0,
              "large_effort": 0
            },
            "ws_pace": "STEADY",
            "ws_health": "OK",
            "ws_priority": "P5",
            "ws_progress": null,
            "ws_start_date": "1508459335",
            "ws_target_date": null,
            "ws_completion_date": null,
            "ws_team_id": "87937",
            "ws_team_name": "MarCom"
          }
        ]
      },
      "team_members": [
        {
          "id": "94658",
          "first_name": "Ana",
          "last_name": "Rodrigues",
          "email": "arodrigues@kikasco.com",
          "team_role": "Manager"
        },
        {
          "id": "100429",
          "first_name": "Dave",
          "last_name": "Cristal",
          "email": "dcristal@kikasco.com",
          "team_role": "Co-manager"
        },
        {
          "id": "105399",
          "first_name": "Teresa",
          "last_name": "Giana",
          "email": "tgiana@kikasco.com",
          "team_role": "Member"
        }
      ]
    }
  }
}

Update teams

[PUT] /team/{team_id}

Change the name of a team, add new and existing users to the team roster, change a member's role on the team, remove users from the team, or add new workstreams.

Note: If you update a team with a new manager, the previous manager will be demoted to a co-manager.

Parameters
team_id	Required The unique numerical id assigned to each team in WorkBoard.
team_name	The name for the team. Each team owned by an individual user must have a unique name.
parent_team_id	Required for functional teams only. The id of the new team's parent in the organization's team hierarchy. If this parameter is passed and the current team is a working group, it will be converted to a functional team.
team_members	The members of the team, and their team roles, as an array: id : the user id of the member (for existing WorkBoard users only). email : the email address of the member (for new users only — they will receive an invitation to join WorkBoard). first_name : the member's first name (for new users only). last_name : the member's last name (for new users only). team_role : the member's role on the team. Permitted values are "manager","co_manager", "exec_viewer", "team_admin", "member" team_access : Used together with id when removing an existing member from the team. Permitted value: "revoke"
team_workstream	The workstreams or projects that should be added to the team, as an array: name : the name of the workstream type : the type of Board that should be added to the team. Permitted values are "1" (Progress Board) or "2" (Custom Agile Board)
team_type	Optional Use this parameter to convert a functional team to a "working_group". Note: when converting a functional team to a working group, do not include the parent_team_id parameter (or set the parent_team_id parameter value to "null"). To convert a working group to a functional team, pass the parent_team_id parameter in your request.

# Sample Request
curl -g -X PUT -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/team/?team_id=87937&team_name=MarCom&team_members[0][id]=100429&team_members[0][team_role]=co_manager&team_members[1][email]=tgiana@kikasco.com&team_members[1][first_name]=Teresa&team_members[1][last_name]=Giana&team_members[1][team_role]=member&team_workstream[0][name]=Demand Generation&team_workstream[0][type]=1&team_workstream[1][name]=PR&team_workstream[1][type]=2"


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 6,
    "team": {
      "team_id": "87937",
      "team_name": "MarCom",
      "team_owner": "94658",
      "team_type": "working group",
      "team_workstream": {
        "workstream_count": 2,
        "workstream": [
          {
            "ws_id": "471321",
            "ws_name": "Demand Generation",
            "ws_objective": "\n",
            "ws_status": "active",
            "ws_type": "team",
            "ws_effort": {
              "low_effort": 0,
              "medium_effort": 0,
              "large_effort": 0
            },
            "ws_pace": "STEADY",
            "ws_health": "OK",
            "ws_priority": "P5",
            "ws_progress": null,
            "ws_start_date": "1508459335",
            "ws_target_date": null,
            "ws_completion_date": null,
            "ws_team_id": "87937",
            "ws_team_name": "MarCom"
          },
          {
            "ws_id": "471322",
            "ws_name": "PR",
            "ws_objective": "\n",
            "ws_status": "active",
            "ws_type": "team",
            "ws_effort": {
              "low_effort": 0,
              "medium_effort": 0,
              "large_effort": 0
            },
            "ws_pace": "STEADY",
            "ws_health": "OK",
            "ws_priority": "P5",
            "ws_progress": null,
            "ws_start_date": "1508459335",
            "ws_target_date": null,
            "ws_completion_date": null,
            "ws_team_id": "87937",
            "ws_team_name": "MarCom"
          }
        ]
      },
      "team_members": [
        {
          "id": "94658",
          "first_name": "Ana",
          "last_name": "Rodrigues",
          "email": "arodrigues@kikasco.com",
          "team_role": "Manager"
        },
        {
          "id": "100429",
          "first_name": "Dave",
          "last_name": "Cristal",
          "email": "dcristal@kikasco.com",
          "team_role": "Co-manager"
        },
        {
          "id": "105399",
          "first_name": "Teresa",
          "last_name": "Giana",
          "email": "tgiana@kikasco.com",
          "team_role": "Member"
        }
      ]
    }
  }
}

Delete a team

PATCH  /team/{team_id}

Delete an entire team and all its workstreams and action items. A successful request will return a 204 code.

Parameters
team_id	Required The unique numerical id assigned to each team in WorkBoard.

# Sample Request
curl -g -X PATCH  -H "Authorization: Bearer {access_token}" https://www.myworkboard.com/wb/apis/team/?team_id={team_id}

# Successful Response
204 no content

Get a Team's Workstreams

[GET] /team/{team_id}/workstream

Get all workstreams belonging to the specified team.

Parameter	Description
team_id	The unique numerical id assigned to each team in WorkBoard.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/team/{team_id}/workstream"

# Sample Response
{  
  "success":true,
  "message":"",
  "data":{  
    "totalCount":1,
    "team":{  
      "team_id":"5632",
      "team_name":"Brand 123",
      "team_owner":"15513",
      "team_type":"working group",
      "team_workstream":{  
        "workstream_count":4,
        "workstream":[  
          {  
            "ws_id":"28149",
            "ws_name":"Team Workstream",
            "ws_objective":"\n",
            "ws_status":"active",
            "ws_type":"team",
            "ws_effort":{  
              "low_effort":"1",
              "medium_effort":"0",
              "large_effort":"0"
            },
            ...
        ]
      }
    }
  }
}

Get a Team's Action Items

[GET] /team/{team_id}/activity/

List details of all action items belonging to the specified team.

Parameter	Description
team_id	The unique numerical id assigned to each team in WorkBoard.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/team/{team_id}/activity/"

# Sample Response
{ 
  "success":true,
  "message":"",
  "data":{ 
    "totalCount":1,
    "team":{ 
      "team_id":"5632",
      "team_name":"Brand 123",
      "team_owner":"15513",
      "team_type":"working group",
      "team_activity":{ 
        "activity_count":4,
        "activity":[ 
          { 
            "ai_id":"95666",
            "ai_description":"one topic",
            "ai_created_at":"1470773153",
            "ai_state":"doing",
            "ai_rating":"green",
            "ai_priority":"medium",
            "ai_effort":"easy",
            "ai_note":"d\u00a0ad\u00a0ad\u00a0dad\n",
            "ai_files":[ 
            ],
            "ai_sub_actions":[ 
              { 
                "sub_ai_id":"95667",
                "sub_ai_description":"oko",
                "sub_ai_owner":"15513"
              }
            ],
            "ai_comments":[ 
            ],
            "ai_due_date":"1470773153",
            "ai_workstream":"28617",
            "ai_team":"5632",
            "ai_loop_members":[ 
              { 
                "user_id":"12822",
                "user_email":"joe@kikasco.com"
              }
            ],
            "ai_tags":null,
            "ai_due_before":"1470614400",
            "ai_owner":"15513",
            "ai_created_by":"15513",
            "ai_url":"https:\/\/wb-api2.com\/wb\/activity\/mywork?do=popup&id=95666"
          },
          ...
        ]
      }
    }
  }
}

Workstream

The Workstream resource represents projects or shared streams of work in WorkBoard. Note that for all API requests to the Workstream resource, the authenticated user must have access to the workstream.

Resource URL : https://www.myworkboard.com/wb/apis/workstream

The following attributes are associated with the Workstream resource:

Attribute	Description
ws_id	Read Only - The unique numerical id assigned to each workstream in WorkBoard.
ws_name	The name of the workstream.
ws_objective	The workstream objective.
ws_team_id	The numerical id of the team to which the workstream belongs.
ws_team_name	The name of the team to which the workstream belongs.
ws_status	The current status of the workstream (active or archived).
ws_type	The type of the workstream (whether it is a personal or team workstream).
ws_pace	The pace of the workstream as set on the workstream dashboard (fast, steady, or slow).
ws_health	The health of the workstream as set on the workstream dashboard (good, ok, or risk).
ws_priority	The priority of the workstream as set on the workstream dashboard (P1, P2, P3, P4 or P5).
ws_effort	The number of action items in the workstream that are set at each level of effort. Includes the following nested attributes: low_effort, medium_effort, and large_effort.
ws_progress	The percentage of the action items in the workstream that have been marked complete.
ws_start_date	The starting date for the workstream as set on the workstream dashboard.
ws_target_date	The end date for the workstream as set on the workstream dashboard.
ws_completion_date	The date on which the workstream is marked complete
ws_activity	Relational resource requests only All of a workstream's action items.

Get Workstreams

[GET] /workstream/{ws_id}

List the details of existing workstream to which the authenticated user has access. Optionally include ws_id to limit the response to details for the specified workstream.

Parameters
ws_id	The unique numerical id assigned to each workstream in WorkBoard.
ws_owner	The numerical user id or email address of the user who currently owns the workstream.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/workstream/{ws_id}"

# Sample Response
{  
  "success":true,
  "message":"",
  "data":{  
    "totalCount":1,
    "workstream":{  
      "ws_id":"26623",
      "ws_name":"Cloud Application Candidates",
      "ws_objective":"Reduce infrastructure costs by moving apps to the cloud",
      "ws_status":"active",
      "ws_type":"team",
      "ws_effort":{  
        "low_effort":"25",
        "medium_effort":"2",
        "large_effort":"1"
      },
      "ws_pace":"SLOW",
      "ws_health":"GOOD",
      "ws_priority":"P4",
      "ws_progress":"14",
      "ws_start_date":null,
      "ws_target_date":null,
      "ws_completion_date":null
    }
  }
}

Create a Workstream

[POST] /workstream

Create a new workstream for a team, including a descriptive narrative and workstream owner.

Parameters
ws_data	The attributes of the workstream you are creating, as an array: ws_name : the name of the workstream. ws_objective : a descriptive narrative or objective statement for the workstream. team_id : the unique numerical id of the workstream's parent team. ws_owner : the user id of the team's manager or co-manager.

# Sample Request
curl -g -X POST -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/workstream/?ws_data[0][team_id]=87937&ws_data[0][ws_name]=Social Media Campaigns&ws_data[0][ws_objective]=Drive website traffic and feed the top of the pipeline with new leads&ws_data[0][ws_owner]=94658"


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "workstream": [
      {
        "ws_id": "471602",
        "ws_name": "Social Media Campaigns",
        "ws_objective": "Drive website traffic and feed the top of the pipeline with new leads",
        "ws_status": "active",
        "ws_type": "team",
        "ws_effort": {
          "low_effort": 0,
          "medium_effort": 0,
          "large_effort": 0
        },
        "ws_pace": "STEADY",
        "ws_health": "OK",
        "ws_priority": "P5",
        "ws_progress": null,
        "ws_start_date": "1508803200",
        "ws_target_date": null,
        "ws_completion_date": null,
        "ws_team_id": "87937",
        "ws_team_name": "MarCom"
      }
    ]
  }
}

Update a Workstream

[PUT] /workstream/{ws_id}

Update a workstream's name, start or end dates, pace, health or priority.

Parameters
ws_id	Required The unique numerical id assigned to each workstream in WorkBoard.
ws_name	The name of the workstream.
ws_start_date	The start date for the workstream as a valid date string or time-stamp.
ws_end_date	The end date for the workstream as a valid date string or time-stamp.
ws_pace	The subjective pace at which work is progressing. Permitted values are: "slow" "fast" "steady"
ws_health	The subjective health of the workstream. Permitted values are: "ok" "good" "risk"
ws_priority	The workstream's priority level, from 1 (highest) to 5 (lowest). Permitted values are: "p1" "p2" "p3" "p4" "p5"
ws_shared_with	Add or remove user access to the workstream (passed as an array): user_id : Required the numerical id or email address associated with the user's WorkBoard account. ws_access : To remove a user's access to the workstream, pass this parameter with the value "revoke"

# Sample Request
curl -g -X PUT -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/workstream/{ws_id}?ws_name=Q4 Social Media Campaigns"


# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "workstream": [
      {
        "ws_id": "471602",
        "ws_name": "Q4 Social Media Campaigns",
        "ws_objective": "Drive website traffic and feed the top of the pipeline with new leads",
        "ws_status": "active",
        "ws_type": "team",
        "ws_effort": {
          "low_effort": 0,
          "medium_effort": 0,
          "large_effort": 0
        },
        "ws_pace": "STEADY",
        "ws_health": "OK",
        "ws_priority": "P5",
        "ws_progress": null,
        "ws_start_date": "1508803200",
        "ws_target_date": null,
        "ws_completion_date": null,
        "ws_team_id": "87937",
        "ws_team_name": "MarCom"
      }
    ]
  }
}

Delete a Workstream

PATCH  /workstream/{ws_id}

Delete a workstream with all its action items. A successful request will return a 204 code.

Parameters
ws_id	Required The unique numerical id assigned to each workstream in WorkBoard.

# Sample Request
curl -g -X PATCH  -H "Authorization: Bearer {access_token}" https://www.myworkboard.com/wb/apis/workstream/?ws_id={ws_id}

# Successful Response
204 no content

Get a Workstream's Action Items

[GET] /workstream/{ws_id}/activity/

List details of all action items belonging to the specified workstream.

Parameter	Description
ws_id	The unique numerical id assigned to each workstream in WorkBoard.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/workstream/{ws_id}/activity/"

# Sample Response
{
  "success" : true,
  "message" : "",
  "data":
    {    
      "totalCount: 1,
      "workstream" : 
        {
          "ws_id" : "22424",
          ...
          "ws_activity" : 
            {
              "activity_count" : 35,
              "activity" : [
                {
                  "ai_id" : "1234"
                  "ai_description" : "One Two Three Four and Done!"
                },
                ...
              ]
            }
        }
    }
}

Data Streams

The Data Stream resource allows you to pipe data from a direct source into WorkBoard so that anyone in your organization can subscribe to it.

Resource URL : https://www.myworkboard.com/wb/apis/stream/

The following attributes are associated with the Data Stream resource:

Attribute	Description
stream_id	Read Only - The unique numerical id assigned to each data stream in WorkBoard.
stream_private_key	Read Only - The private key generated when the data stream was set up in WorkBoard.
stream_name	The name of the data stream.
stream_frequency	The update frequency of the data stream (Daily, Weekly, Monthly, Quarterly).
stream_category	The category assigned to the data stream.
stream_data_type	The data type in the stream (Numbers, Currency, or Percentage).
stream_description	An optional description of the data stream.
stream_active	Active or Inactive.
stream_connector_id	Unique identifier for the connector system
stream_data_last_updated	The date of the last update (in Unix timestamp format).
stream_last_data_value	The last update value.

Create Data Streams

[POST] apis/stream/

Create a new data stream.

# Sample Post
{
  "stream_name": "Sample Data Stream",
  "stream_description": "A Sample Data Stream",
  "stream_data_type": "percentage",
  "stream_frequency": "weekly",
  "stream_category": "category-1",
  "stream_permission": [
    {"id": "{user_id}","type": "user"},
    {"id": "{team_id}","type": "team"},
    {"id": "{org_id}","type": "org"}
  ]
}


# Sample Response
{
   "success":true,
   "message":"",
   "data":{
      "totalCount":1,
      "stream":{
         "stream_id":"123456",
         "stream_private_key":"123456",
         "stream_name":"Sample Data Stream",
         "stream_frequency":"Weekly",
         "stream_category":"category-1",
         "stream_data_type":"Percentage",
         "stream_description":"A Sample Data Stream",
         "stream_active":"Active",
         "stream_connector_id":null,
         "stream_data_last_updated":null,
         "stream_last_data_value":null
      }
   }
}

Get Data Streams

[GET] apis/stream/

Get the details of data streams to which the authenticated user has access.

# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/stream/"

# Sample Response
{
  "success":true,
  "message":"",
  "data":{
    "totalCount":1,
    "stream":{
      "streams":[
        {
          "stream_id":"1ae2c86f357d116f5585cb962e2a4024c",
          "stream_private_key":"ae2c86f357d116f5585cb962e2a4024cc9f675df59f443b4ec8c1e3841b4d81b",
          "stream_name":"Data Stream 1",
          "stream_frequency":"Daily",
          "stream_category":"",
          "stream_data_type":"Numbers",
          "stream_description":null,
          "stream_active":"Active",
          "stream_connector_id":null,
          "stream_data_last_updated":"1528162592",
          "stream_last_data_value":null
        }
      ]
    }
  }
}

Update Data Streams

[POST] /stream/{stream_id}

Update a data stream.

You will need to set two headers:

Content-Type: Set to "application/json"
X-stream-signature: Secure this URL by passing the stream_private_key that was generated when the data stream was set up in WorkBoard.

To pass the data to the data stream, you need to construct the JSON payload according to the format in the example at right.

Parameters
connector_id	Unique identifier for the system
connector_data	The updated data value (passed as an object): value : the update value
connector_attributes	Optional - any additional properties (passed as an object). Example uses:" source : The source of the data. comment : A comment on the update.
connector_property	Optional Use: comment : A narrative on the current KR update.

Note: Our API does not yet process the connector_attributes node; it is included for potential use in the future.

# Sample Payload
{
  "data" :{
    "stream" : {
      "connector" : {
        "connector_id" : "12345",
        "connector_data" : {"value" : "0.97", "date": "2019-07-21"},
        "connector_attributes" : { // any additional property
          "source" : "From SAP",
          "comment" : "Computed weekly"
        },
        "connector_property": {
        "comment": "Comment on weekly update"
        }
      }
    }
  }
}

Webhooks

WorkBoard's webhooks allow you to post data from your external applications into WorkBoard by sending a formatted JSON payload via HTTP POST request to the secret WorkBoard URL generated for your application. Currently WorkBoard only supports incoming webhooks; outgoing webhooks will be available soon.

Incoming Webhooks

WorkBoard's incoming webhooks offer an easy way to update metric data in WorkBoard using a simple HTTP post.

If you are new to webhooks, or if this is the first time you are working with WorkBoard webhooks, we recommend first using one of WorkBoard's pre-built connectors to easily update metric data from Google Spreadsheets, Excel or CSV files.

For more advanced applications which you can customize per your requirements, you can code your own POST requests using the global hook URL which WorkBoard will generate for you:

1. Click here to get your webhook URL. Note: If you haven't yet tried one of our pre-built connectors, you will first need to click one of the three options (Google Spreadsheet, Microsoft Excel, or From CSV) to generate your private webhook_hash.

2. Click the link labelled "Getting Off the Ground - Know more about Webhooks and advanced customizations." You will find your webhook URL there. In the URL, you will see a webhook_hash, which is private to you.

Parameters
metric_id	Read Only. The unique numerical id assigned to each metric
metric_data	The value you want to use to update the metric.
metric_comment	Include this parameter to add a comment to this metric data update.

# Sample webhook URL
https://www.myworkboard.com/wb/apis/hook/{webhook_hash}


# Sample cURL request
curl -X POST -d "metric_id={metric_id}&metric_data={metric_data}&metric_comment={metric_comment}" https://myworkboard.com/wb/apis/hook/{webhook_hash}

Pre-Built Connectors

WorkBoard provides pre-built webhook templates for some common metric data sources, including Google Spreadsheets, Excel, or CSV files.

WorkBoard API v1.0

Overview

Authentication

Errors

API Reference

Users

Get user profile

Create a new user

Update user profile

Delete user

Get user goals

Get user teams

Bulk User Provisioning

Goals

Get goals

Create a goal

Get a goal's metric

Get a goal's alignment

Metric

Get all metrics

Get one metric (current user)

Add metric data

Get a metric's tags

Get a list of metrics' tags

Get all metrics mapped to a tag

Add tags to a single metric

Add tags to multiple metrics

Remove a metric's tags

Tags

Get all tags

Get one tag

Get all tags for a group

Get all metrics mapped to a tag

Add tags to a single metric

Add tags to multiple metrics

Remove a metric's tags

Action Item

Get Action Items

Create an Action Item

Update an Action Item

Team

Get Teams

Create a team

Update teams

Delete a team

Get a Team's Workstreams

Get a Team's Action Items

Workstream

Get Workstreams

Create a Workstream

Update a Workstream

Delete a Workstream

Get a Workstream's Action Items

Data Streams

Create Data Streams

Get Data Streams

Update Data Streams

Webhooks

Incoming Webhooks

Pre-Built Connectors