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 superuser 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.

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

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.
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/"
# or
curl -g -X GET "https://www.myworkboard.com/wb/apis/user/?token={access_token}"

# 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"
      }
    ]
  }
}
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".
# 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",
           "timezone": "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. Optionally transfer the user's meetings, action items, and OKRs to another user. A successful request will return a 204 code.

Parameters
action Required. Choose whether to disable the user's access or delete them from the system. Permitted values are:

"disable" - Disable the user and block them from accessing WorkBoard

"admin:delete" - Disable the user, block them from accessing WorkBoard, transfer the user's action items to the manager or the person specified with the transfer_to parameter, cancel meetings, and remove the user from all teams and reporting relationships.

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.
transfer_to Optional. Transfer the user's action items, teams, meetings and OKRs to another existing user. Permitted values include the new owner's numerical user id or email address.
# Sample Request
curl -g -X PATCH  -H "Authorization: Bearer {access_token}" https://www.myworkboard.com/wb/apis/user/?user_id={user_id}&transfer_to={manager_user_id}&action={disable|admin:delete}

# 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.

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.
direct_manager: Optional. the email address of the user's direct manager
# 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_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

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.
state The current state of the goal; permitted values are "Active" (default) or "Closed".
# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://myworkboard.com/wb/goal/"
# or
curl -g -X GET "https://myworkboard.com/wb/goal/?token={access_token}"


# 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_id 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/goal/{goal_id}/metric/{metric_id}"
# or
curl -g -X GET "https://myworkboard.com/wb/goal/{goal_id}/metric/{metric_id}?token={access_token}"


# 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
    }
  }
}

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_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_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

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

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

# 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"
    }
  }
}

Meeting

The Meeting resource represents a team meeting or 1on1 meeting in WorkBoard.

Use the Meeting resource to query, create, delete or update WorkBoard meetings.

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

The following attributes are associated with the Meeting resource:

Attribute Description
meeting_id Read Only - The unique numerical id assigned to each team or 1on1 meeting in WorkBoard.
meeting_name The name of the meeting
meeting_objective A description of the meeting objective
meeting_location A text field for the meeting location
meeting_scheduled_time The scheduled start time for the meeting
meeting_re_occurrence_rule A rule defining the frequency and interval at which the meeting will recur; uses iCalendar specifications per RFC 2445. Example: RRULE:FREQ=WEEKLY; UNTIL=20160418T233000Z; INTERVAL=2;
meeting_attendees Comma-separated list of the email addresses of meeting attendees; the email addresses are those associated with each user's account in WorkBoard
meeting_created_by Optional The numerical user id or email address of the user creating the meeting. If this parameter is not set, the value will default to the user id of the currently authenticated user.
number_of_topic Required for adding agenda items The total number of agenda topics you are adding to a meeting in a POST or PUT request.
number_of_takeaway Required for adding takeaways The total number of takeaways you are adding to a meeting in a POST or PUT request.
meeting_topic_type_{#} Optional The type of agenda topic. Possible values are IDEA, DECISION, NOTE, RESOLVED, DISCUSSION, FYI, ISSUE. The {#} at the end of the parameter must match the {#} at the end of the meeting_topic_description_{#} parameter
meeting_topic_description_{#} Required if meeting_topic_type_{#} is included. The description of the agenda topic. The {#} at the end of the parameter must match the {#} at the end of the meeting_topic_type_{#} parameter
meeting_takeaway_type_{#} Optional The type of meeting takeaway. Possible values are IDEA, DECISION, NOTE, RESOLVED, DISCUSSION, FYI, ISSUE. The {#} at the end of the parameter must match the {#} at the end of the meeting_takeaway_description_{#} parameter
meeting_takeaway_description_{#} Required if meeting_takeaway_type_{#} is included. The description of the meeting takeaway. The {#} at the end of the parameter must match the {#} at the end of the meeting_takeaway_type_{#} parameter
include_topic Optional Include this parameter in your GET request to get a list of agenda topics for the meeting. Value must be set to "yes". (Note, the request will not return goals or action items that have been added to the meeting agenda)
include_takeaway Optional Include this parameter in your GET request to get a list of takeaways for the meeting. Value must be set to "yes".
meeting_status Meeting status (will be included in GET responses)
meeting_url WorkBoard URL to access the meeting
meeting_type The type of meeting, whether 1on1 or team meeting. Possible values are:
"1on1"
"team"
"group"

Get an existing meeting

[GET] /meeting/{meeting_id}

List the details of an existing meeting. NOTE: The authenticated user must have permission to access the meeting.

Parameters
meeting_id The unique numerical id assigned to each team or 1on1 meeting in WorkBoard.
meeting_created_by The numerical user id or email address of the user creating the meeting. If this parameter is not set, the value will default to the user id of the currently authenticated user.
# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/meeting/{meeting_id}"

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

# Sample Response
{
  "success": true,
  "message": "",
  "data": {
    "totalCount": 1,
    "meeting": {
      "meeting_id": "13738",
      "meeting_name": "Cloud Candidates Review",
      "meeting_created_by": "94658",
      "meeting_type": "group",
      "meeting_attendees": "allen.bart@kikasco.com,richard.stevens@kikasco.com",
      "meeting_scheduled_time": "2016-10-07T20:00:00",
      "meeting_location": "Skyline Conference Room",
      "meeting_objective": "Finalize a candidate list of apps to move to the cloud"
    }
  }
}

Create a meeting

[POST] /meeting/

Create a meeting in WorkBoard using the parameters below.

NOTE, to create topics or takeaways, include the meeting_topic_type_{#} (or meeting_takeaway_type_{#}) / meeting_topic_description_{#} (or meeting_takeaway_description_{#}) parameters as in these examples:

meeting_topic_type_1 : IDEA
meeting_topic_description_1 : Topic description

meeting_topic_type_2 : DECISION
meeting_topic_description_2 : Topic description

meeting_topic_type_3 : NOTE
meeting_topic_description_3 : Topic description

meeting_topic_type_4 : ISSUE
meeting_topic_description_4 : Topic description

Parameters
meeting_name Required for POST requests. The name of the meeting
meeting_objective A description of the meeting objective
meeting_location A text field for the meeting location
meeting_scheduled_time The scheduled start time for the meeting
meeting_re_occurrence_rule A rule defining the frequency and interval at which the meeting will recur; uses iCalendar specifications per RFC 2445. Example: RRULE:FREQ=WEEKLY; UNTIL=20160418T233000Z; INTERVAL=2;
meeting_attendees Comma-separated list of the email addresses of meeting attendees; the email addresses are those associated with each user's account in WorkBoard
meeting_created_by Optional The numerical user id or email address of the user creating the meeting. If this parameter is not set, the value will default to the user id of the currently authenticated user.
number_of_topic Required for adding agenda items The total number of agenda topics you are adding to a meeting in a POST or PUT request.
number_of_takeaway Required for adding takeaways The total number of takeaways you are adding to a meeting in a POST or PUT request.
meeting_topic_type_{#} Optional The type of agenda topic. Possible values are IDEA, DECISION, NOTE, RESOLVED, DISCUSSION, FYI, ISSUE. The {#} at the end of the parameter must match the {#} at the end of the meeting_topic_description_{#} parameter
meeting_topic_description_{#} Required if meeting_topic_type_{#} is included The description of the agenda topic. The {#} at the end of the parameter must match the {#} at the end of the meeting_topic_type_{#} parameter
meeting_takeaway_type_{#} Optional The type of meeting takeaway. Possible values are IDEA, DECISION, NOTE, RESOLVED, DISCUSSION, FYI, ISSUE. The {#} at the end of the parameter must match the {#} at the end of the meeting_takeaway_description_{#} parameter
meeting_takeaway_description_{#} Required if meeting_takeaway_type_{#} is included The description of the meeting takeaway. The {#} at the end of the parameter must match the {#} at the end of the meeting_takeaway_type_{#} parameter
meeting_type The type of meeting, whether 1on1 or team meeting. Possible values are:
"1on1"
"group"
# Sample Request
curl -g -X POST -H 'Authorization: bearer {access_token}' 'https://myworkboard.com/wb/apis/meeting/'
# or
curl -g -X POST 'https://myworkboard.com/wb/apis/meeting/?token={access_token}'

Update an existing meeting

[PUT] /meeting/{meeting_id}

Update an existing meeting in WorkBoard using the parameters below.

NOTE, to create topics or takeaways, include the meeting_topic_type_{#} (or meeting_takeaway_type_{#}) / meeting_topic_description_{#} (or meeting_takeaway_description_{#}) parameters as in these examples:

meeting_topic_type_1 : IDEA
meeting_topic_description_1 : Topic description

meeting_topic_type_2 : DECISION
meeting_topic_description_2 : Topic description

meeting_topic_type_3 : NOTE
meeting_topic_description_3 : Topic description

meeting_topic_type_4 : ISSUE
meeting_topic_description_4 : Topic description

Parameters
meeting_id Read Only - Required. The unique numerical id assigned to each team or 1on1 meeting in WorkBoard.
meeting_name The name of the meeting
meeting_objective A description of the meeting objective
meeting_location A text field for the meeting location
meeting_scheduled_time The scheduled start time for the meeting
meeting_re_occurrence_rule A rule defining the frequency and interval at which the meeting will recur; uses iCalendar specifications per RFC 2445. Example: RRULE:FREQ=WEEKLY; UNTIL=20160418T233000Z; INTERVAL=2;
meeting_attendees Comma-separated list of the email addresses of meeting attendees; the email addresses are those associated with each user's account in WorkBoard
number_of_topic Required for adding agenda items The total number of agenda topics you are adding to a meeting in a POST or PUT request.
number_of_takeaway Required for adding takeaways The total number of takeaways you are adding to a meeting in a POST or PUT request.
meeting_topic_type_{#} Optional The type of agenda topic. Possible values are IDEA, DECISION, NOTE, RESOLVED, DISCUSSION, FYI, ISSUE. The {#} at the end of the parameter must match the {#} at the end of the meeting_topic_description_{#} parameter
meeting_topic_description_{#} Required if meeting_topic_type_{#} is included The description of the agenda topic. The {#} at the end of the parameter must match the {#} at the end of the meeting_topic_type_{#} parameter
meeting_takeaway_type_{#} Optional The type of meeting takeaway. Possible values are IDEA, DECISION, NOTE, RESOLVED, DISCUSSION, FYI, ISSUE. The {#} at the end of the parameter must match the {#} at the end of the meeting_takeaway_description_{#} parameter
meeting_takeaway_description_{#} Required if meeting_takeaway_type_{#} is included The description of the meeting takeaway. The {#} at the end of the parameter must match the {#} at the end of the meeting_takeaway_type_{#} parameter
# Sample Request
curl -g -X PUT -H 'Authorization: bearer {access_token}' 'https://myworkboard.com/wb/apis/meeting/{meeting_id}/'
# or
curl -g -X PUT 'https://myworkboard.com/wb/apis/meeting/{meeting_id}/?token={access_token}'

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 an Action Item

[GET] /activity/{ai_id}

List the details of an existing action item.

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. The default value is 50.
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.
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}"

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

# 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/"

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

# 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}/"

# or
curl -g -X PUT "https://www.myworkboard.com/wb/apis/activity/{ai_id}/?token={access_token}"


# 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.

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".
# Sample Request
curl -g -X GET -H "Authorization: bearer {access_token}" "https://www.myworkboard.com/wb/apis/team/{team_id}"

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

# 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.

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)
# 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"

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

# 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/"

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

# 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}"

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

# 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/"

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

# 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.

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

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

# 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:

  1. Content-Type: Set to "application/json"
  2. 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 array):
value : the update value
connector_attributes Optional - any additional properties (passed as an array). Example uses:
source : The source of the data.
comment : A comment on the 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" : "2102ab",
        "connector_data" : {"value" : "0.97"},
        "connector_attributes" : { // any additional property
          "source" : "From SAP",
          "comment" : "Computed weekly"
        }
      }
    }
  }
}

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.