NAV Navbar
javascript shell

Just3Things Public API

Our RESTful JSON API allows you to write your own integrations using the endpoints described. If you need any help using our API please feel free to contact us.

Getting Started

Before you can start using our public API you'll need:

  1. An active Just3Things account.
  2. A client_id and client_secret that can be used to authenticate users against our API. Contact us to request these.

Authentication

Just3Things Public API is authenticated using OAuth 2.0. Once you have a client_id and client_secret your integration can authenticate to our API using the Authorization Code Flow.

Initial Authentication

All our endpoints authenticate each request by checking for a Bearer token in the Authorization header of the request. To obtain a Bearer token (in our case an OAuth access_token) we need to authorise the user first using the steps below.

Step 1 - Redirect your user to our OAuth endpoint

The first step in authenticating a user to allow them access to our API, is to redirect them to our authentication server. Here they can login and authorise your integration, allowing it access to their account.

HTTP Request

Redirect the user to the authentication server

// Within your client side code
window.location(`https://api.just3things.com/auth/oauth2?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>`)
# We do not recommend you trying to authenitcate via shell
curl "https://api.just3things.com/auth/oauth2?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>"

GET https://api.just3things.com/auth/oauth2

URL Parameters

response_type must be set to code.

Parameter Description
CLIENT_ID The client_id we provided when setting up your integration.
REDIRECT_URI The URI you would like the user redirected back to after authenticating. NOTE: This must match one of the allowed URIs you provided us.

Redirect URI

Once the user has authenticated you will be redirected back to the URI you provided as redirect_uri in the request above.

You will be returned one of two parameters as query parameters:

Parameter Description
?code= The Authorization code to be used in step 2 below.
?error= The user either cancelled the authentication or there was an error.

Step 2 - Exchange an Authorization Code for a Access Token

Once you have an authorization code (see step 1 above) you can exchange it for an access_token that can be used in all API requests.

HTTP Request

Exchange an authorization code for a access token

fetch("https://api.just3things.com/token", {
  "method": "POST",
  "headers": {
    "content-type": "application/x-www-form-urlencoded"
  },
  "body": {
    "client_secret": "<CLIENT_SECRET>",
        "client_id": "<CLIENT_ID>",
        "grant_type": "authorization_code",
        "code": "<AUTHORIZATION_CODE>",
        "redirect_uri": "<REDIRECT_URI>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request POST \
  --url https://api.just3things.com/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_secret=<CLIENT_SECRET> \
  --data client_id=<CLIENT_ID> \
  --data grant_type=authorization_code \
  --data code=<AUTHORIZATION_CODE> \
  --data redirect_uri=<REDIRECT_URI>

POST https://api.just3things.com/token

POST Parameters (x-www-form-urlencoded)

Parameter Description
CLIENT_ID The client_id we provided when setting up your integration.
CLIENT_SECRET The client_secret we provided when setting up your integration.
AUTHORIZATION_CODE The code the user was redirected back with in step 1.
REDIRECT_URI The URI that the user was redirected back to. NOTE: This must match the one you used in step 1.

HTTP Response

Response

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "refresh_token": "<REFRESH_TOKEN>",
  "refresh_token_expires_in": 31536000,
  "token_type": "Bearer"
}
{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "refresh_token": "<REFRESH_TOKEN>",
  "refresh_token_expires_in": 31536000,
  "token_type": "Bearer"
}
Property Description
access_token Use this as your Bearer token in all API requests.
expires_in The length of time in seconds (from issue) the access_token is valid for.
refresh_token Use this to request a new access_token once the provided one expires.
refresh_token_expires_in The length of time in seconds (from issue) the refresh_token is valid for.
token_type This tells you this access_token can be used as a Bearer token.

Step 3 - Access our API

You can now access our public API at https://api.just3things.com/v1/<ACCOUNT_KEY>

Have a look at the contents on the left for details on the various available endpoints

URL Parameters

Parameter Description
ACCOUNT_KEY The account key for the account context you would like to access this user in.

Refreshing Access Tokens

You can refresh your access_token at any time using the /token endpoint.

HTTP Request

Refresh your access_token using a refresh_token

fetch("https://api.just3things.com/token", {
  "method": "POST",
  "headers": {
    "content-type": "application/x-www-form-urlencoded"
  },
  "body": {
    "client_secret": "<CLIENT_SECRET>",
    "client_id": "<CLIENT_ID>",
    "grant_type": "refresh_token",
    "refresh_token": "<REFRESH_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request POST \
  --url https://api.just3things.com/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_secret=<CLIENT_SECRET> \
  --data client_id=<CLIENT_ID> \
  --data grant_type=refresh_token \
  --data refresh_token=<REFRESH_TOKEN>

POST https://api.just3things.com/token

POST Parameters (x-www-form-urlencoded)

Parameter Description
CLIENT_ID The client_id we provided when setting up your integration.
CLIENT_SECRET The client_secret we provided when setting up your integration.
REFRESH_TOKEN The refresh_token provided when you authenticated or last refreshed.

HTTP Response

Response

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "refresh_token": "<REFRESH_TOKEN>",
  "refresh_token_expires_in": 31536000,
  "token_type": "Bearer"
}
{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "refresh_token": "<REFRESH_TOKEN>",
  "refresh_token_expires_in": 31536000,
  "token_type": "Bearer"
}
Property Description
access_token Use this as your Bearer token in all API requests.
expires_in The length of time in seconds (from issue) the access_token is valid for.
refresh_token Use this to request a new access_token once the provided one expires.
refresh_token_expires_in The length of time in seconds (from issue) the refresh_token is valid for.
token_type This tells you this access_token can be used as a Bearer token.

Users

You can use the API to get information about any user within an account you have access to. As users may have access to several accounts you must request the user specifying an account.

For example, requesting /account-1/users/me or /account-2/users/me will return the same user but some details will be different based on the account context, i.e. position.

Get All Users

Get all the users for an account

Get all the users for an account

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/users?limit=2&cursor=1974267", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url https://api.just3things.com/v1/<ACCOUNT_KEY>/users/users?limit=2&cursor=1974267 \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

GET https://api.just3things.com/v1/<ACCOUNT_KEY>/users

URL Parameters

Parameter Description
ACCOUNT_KEY The account key for the account to select the user from.

Query Parameters

Parameter Description
limit Limit the number of results returned. Default: 10 (Valid range 1-100)
cursor The id of the user to select from, the nextCursor value is returned by each call of the API allowing you to page through the results

HTTP Response

Response

{
  "data": [
    {
      "id": 1974267,
      "email": "a.user@company.com",
      "firstName": "A",
      "lastName": "User",
      "fullName": "A User",
      "initials": "AU",
      "bio": "Some bio about a user",
      "bioHTML": "<p>Some bio about another user</p>",
      "bioText": "Some bio about another user",
      "avatarURL": "https://my.avatar.com",
      "avatarImage": "data:image/svg+xml;base64...",
      "avatarColour": "#a39529",
      "position": "CEO",
      "deletedAt": null
    },
    {
      "id": 1974268,
      "email": "another.user@company.com",
      "firstName": "Another",
      "lastName": "User",
      "fullName": "Another User",
      "initials": "AU",
      "bio": "Some bio about another user",
      "bioHTML": "<p>Some bio about another user</p>",
      "bioText": "Some bio about another user",
      "avatarURL": "https://my.avatar.com",
      "avatarImage": "data:image/svg+xml;base64...",
      "avatarColour": "#a39529",
      "position": "Finance Director",
      "deletedAt": null
    },
  ],
  "nextCursor": 1974269
}
{
  "data": [
    {
      "id": 1974267,
      "email": "a.user@company.com",
      "firstName": "A",
      "lastName": "User",
      "fullName": "A User",
      "initials": "AU",
      "bio": "Some bio about a user",
      "bioHTML": "<p>Some bio about another user</p>",
      "bioText": "Some bio about another user",
      "avatarURL": "https://my.avatar.com",
      "avatarImage": "data:image/svg+xml;base64...",
      "avatarColour": "#a39529",
      "position": "CEO",
      "deletedAt": null
    },
    {
      "id": 1974268,
      "email": "another.user@company.com",
      "firstName": "Another",
      "lastName": "User",
      "fullName": "Another User",
      "initials": "AU",
      "bio": "Some bio about another user",
      "bioHTML": "<p>Some bio about another user</p>",
      "bioText": "Some bio about another user",
      "avatarURL": "https://my.avatar.com",
      "avatarImage": "data:image/svg+xml;base64...",
      "avatarColour": "#a39529",
      "position": "Finance Director",
      "deletedAt": null
    },
  ],
  "nextCursor": 1974269
}
Property Description
data The returned users are wrapped in a data property.
nextCursor The id to use for cursor in the following request to get the next page, null if there are no more users to load

User Object

Property Description
id The user's id.
email The user's email.
firstName The user's given name.
lastName The user's family name.
fullName The user's full name.
initials The user's initials (used for their default avatar in Just3Things).
bio A short biography the user has added about themselves.
bioHTML A short biography the user has added about themselves in HTML format.
bioText A short biography the user has added about themselves in plaintext.
position The user's position or job title.
avatarURL If the user has uploaded an avatar picture this property is a publicly accessible link to that avatar.
avatarColour The colour assigned to the user's avatar by the Just3Things system
avatarImage Some users have a Base64 encoded image as their avatar, often this is a generated SVG avatar based on their initials and avatarColour

Get Authenticated User

Get information about the currently authenticated user.

HTTP Request

Get the authenticated user

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/users/me", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url https://api.just3things.com/v1/<ACCOUNT_KEY>/users/me \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

GET https://api.just3things.com/v1/<ACCOUNT_KEY>/users/me

URL Parameters

Parameter Description
ACCOUNT_KEY The account key for the account to select the user from.

HTTP Response

Response

{
  "data": {
    "id": 1974267,
    "email": "a.user@company.com",
    "firstName": "Another",
    "lastName": "User",
    "fullName": "Another User",
    "initials": "AU",
    "bio": "Some bio about another user",
    "bioHTML": "<p>Some bio about another user</p>",
    "bioText": "Some bio about another user",
    "avatarURL": "https://my.avatar.com",
    "avatarImage": "data:image/svg+xml;base64...",
    "avatarColour": "#a39529",
    "position": "CEO",
    "deletedAt": null
  }
}
{
  "data": {
    "id": 1974267,
    "email": "a.user@company.com",
    "firstName": "Another",
    "lastName": "User",
    "fullName": "Another User",
    "initials": "AU",
    "bio": "Some bio about another user",
    "bioHTML": "<p>Some bio about another user</p>",
    "bioText": "Some bio about another user",
    "avatarURL": "https://my.avatar.com",
    "avatarImage": "data:image/svg+xml;base64...",
    "avatarColour": "#a39529",
    "position": "CEO",
    "deletedAt": null
  }
}

The returned user is wrapped in a data property.

Property Description
id The user's id.
email The user's email.
firstName The user's given name.
lastName The user's family name.
fullName The user's full name.
initials The user's initials (used for their default avatar in Just3Things).
bio A short biography the user has added about themselves.
bioHTML A short biography the user has added about themselves in HTML format.
bioText A short biography the user has added about themselves in plaintext.
position The user's position or job title.
avatarURL If the user has uploaded an avatar picture this property is a publicly accessible link to that avatar.
avatarColour The colour assigned to the user's avatar by the Just3Things system
avatarImage Some users have a Base64 encoded image as their avatar, often this is a generated SVG avatar based on their initials and avatarColour

Get a User

Get information about a user using their id.

HTTP Request

Get the requested user

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/users/<USER_ID>", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url https://api.just3things.com/v1/<ACCOUNT_KEY>/users/<USER_ID> \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

GET https://api.just3things.com/v1/<ACCOUNT_KEY>/users/<USER_ID>

URL Parameters

Parameter Description
ACCOUNT_KEY The account key for the account to select the user from.
USER_ID The id of the user you would like to request

HTTP Response

Response

{
  "data": {
    "id": 1974267,
    "email": "a.user@company.com",
    "firstName": "Another",
    "lastName": "User",
    "fullName": "Another User",
    "initials": "AU",
    "bio": "Some bio about another user",
    "bioHTML": "<p>Some bio about another user</p>",
    "bioText": "Some bio about another user",
    "avatarURL": "https://my.avatar.com",
    "avatarImage": "data:image/svg+xml;base64...",
    "avatarColour": "#a39529",
    "position": "CEO",
    "deletedAt": null
  }
}
{
  "data": {
    "id": 1974267,
    "email": "a.user@company.com",
    "firstName": "Another",
    "lastName": "User",
    "fullName": "Another User",
    "initials": "AU",
    "bio": "Some bio about another user",
    "bioHTML": "<p>Some bio about another user</p>",
    "bioText": "Some bio about another user",
    "avatarURL": "https://my.avatar.com",
    "avatarImage": "data:image/svg+xml;base64...",
    "avatarColour": "#a39529",
    "position": "CEO",
    "deletedAt": null
  }
}

The returned user is wrapped in a data property.

Property Description
id The user's id.
email The user's email.
firstName The user's given name.
lastName The user's family name.
fullName The user's full name.
initials The user's initials (used for their default avatar in Just3Things).
bio A short biography the user has added about themselves.
bioHTML A short biography the user has added about themselves in HTML format.
bioText A short biography the user has added about themselves in plaintext.
position The user's position or job title.
avatarURL If the user has uploaded an avatar picture this property is a publicly accessible link to that avatar.
avatarColour The colour assigned to the user's avatar by the Just3Things system
avatarImage Some users have a Base64 encoded image as their avatar, often this is a generated SVG avatar based on their initials and avatarColour

Pillars

You can use the API to get all the current pillars for an account.

Get all Pillars

Get a list of pillars for the account.

HTTP Request

Get all the pillars

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/pillars", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url https://api.just3things.com/v1/<ACCOUNT_KEY>/pillars \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

https://api.just3things.com/v1/<ACCOUNT_KEY>/pillars

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the pillars from.

HTTP Response

Response

{
  "data": [
    {
      "id": 46209,
      "accountId": 2,
      "title": "Be Europe's Most Trusted Online Retailer",
      "active": true,
      "archivedAt": null,
      "archivedBy": null,
      "createdAt": "2019-07-22T09:12:26.176Z",
      "createdBy": 1775,
      "updatedAt": "2019-07-22T09:12:26.176Z",
      "updatedBy": 1775,
      "deletedAt": null
    },
    {
      "id": 46210,
      "accountId": 2,
      "title": "Double Global Revenue",
      "active": true,
      "archivedAt": null,
      "archivedBy": null,
      "createdAt": "2019-07-22T09:12:33.738Z",
      "createdBy": 1775,
      "updatedAt": "2019-07-22T09:12:33.738Z",
      "updatedBy": 1775,
      "deletedAt": null
    },
    {
      "id": 46211,
      "accountId": 2,
      "title": "A Loyal Customer Base Across 15 Markets",
      "active": true,
      "archivedAt": null,
      "archivedBy": null,
      "createdAt": "2019-07-22T09:12:40.047Z",
      "createdBy": 1775,
      "updatedAt": "2019-07-22T09:12:40.047Z",
      "updatedBy": 1775,
      "deletedAt": null
    }
  ]
}
{
  "data": [
    {
      "id": 46209,
      "accountId": 2,
      "title": "Be Europe's Most Trusted Online Retailer",
      "active": true,
      "archivedAt": null,
      "archivedBy": null,
      "createdAt": "2019-07-22T09:12:26.176Z",
      "createdBy": 1775,
      "updatedAt": "2019-07-22T09:12:26.176Z",
      "updatedBy": 1775,
      "deletedAt": null
    },
    {
      "id": 46210,
      "accountId": 2,
      "title": "Double Global Revenue",
      "active": true,
      "archivedAt": null,
      "archivedBy": null,
      "createdAt": "2019-07-22T09:12:33.738Z",
      "createdBy": 1775,
      "updatedAt": "2019-07-22T09:12:33.738Z",
      "updatedBy": 1775,
      "deletedAt": null
    },
    {
      "id": 46211,
      "accountId": 2,
      "title": "A Loyal Customer Base Across 15 Markets",
      "active": true,
      "archivedAt": null,
      "archivedBy": null,
      "createdAt": "2019-07-22T09:12:40.047Z",
      "createdBy": 1775,
      "updatedAt": "2019-07-22T09:12:40.047Z",
      "updatedBy": 1775,
      "deletedAt": null
    }
  ]
  }

The returned pillars are wrapped in a data property.

Property Description
id The id of the pillar.
accountId The id of the account that the pillar belongs to.
title The title of the pillar
active Whether the pillar is active. A pillar is active when it has not been archived or deleted.
archivedAt If not null the pillar was archived on this date.
archivedBy If the pillar has been archived, the userId of the user that archived it.
createdAt The date this pillar was created.
createdBy The userId of the user that created this pillar.
updatedAt The date the pillar was last edited.
createdBy The userId of the user that last updated this pillar.

Goals

You can use the API to get information about any goal within an account that you have access to as well as make a check-in on any metric goals you are a member of.

Get All Goals

Get a list of all goals within an account

HTTP Request

Get all goals for an account

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/goals?cursor=1234567&limit=10&type=keyresult", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url 'https://api.just3things.com/v1/<ACCOUNT_KEY>/goals?cursor=1234567&limit=10&type=keyresult' \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

https://api.just3things.com/v1/<ACCOUNT_KEY>/goals

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the goals from.

Query Parameters

Parameter Description
limit Limit the number of results returned. Default: 10 (Valid range 1-100)
cursor The id of the goal to select from, the nextCursor value is returned by each call of the API allowing you to page through the results.
type The type of goal to return can be one of objective, keyresult (returns both metric and milestone goals), metric or milestone.

HTTP Response

Response

{
  "data": [{
    "id": 1234567,
    "accountId": 2,
    "active": false,
    "archivedAt": "2020-03-02T23:45:00.140Z",
    "archivedBy": null,
    "cachedPercentageComplete": 0,
    "completed": false,
    "completedAt": null,
    "completedBy": null,
    "computedRAG": "R",
    "createdAt": "2019-09-19T15:11:10.140Z",
    "createdBy": 1775,
    "currentValue": 10,
    "description": "",
    "descriptionHTML": null,
    "descriptionText": null,
    "durationInDays": 134,
    "durationInWeeks": 19,
    "endDate": "2020-01-31T00:00:00.000Z",
    "private": false,
    "progressEnabled": false,
    "redOffset": -9,
    "redStart": -9,
    "redValue": 21,
    "startDate": "2019-09-18T23:00:00.000Z",
    "startValue": 0,
    "targetForecast": [],
    "targetType": ">",
    "targetValue": 30,
    "title": "A metric goal 1",
    "type": "metric",
    "unitTypeId": 5772,
    "updatedAt": "2020-03-02T23:45:00.141Z",
    "valueChange": {
      "value": 10,
      "checkInDate": "2019-09-18T23:00:00.000Z",
      "previousCheckInDate": "2019-09-18T23:00:00.000Z"
    },
    {
    "id": 1234568,
    "accountId": 2,
    "active": false,
    "archivedAt": "2020-03-02T23:45:00.140Z",
    "archivedBy": null,
    "cachedPercentageComplete": 0,
    "completed": false,
    "completedAt": null,
    "completedBy": null,
    "computedRAG": "R",
    "createdAt": "2019-09-19T15:11:10.140Z",
    "createdBy": 1775,
    "currentValue": 10,
    "description": "",
    "descriptionHTML": null,
    "descriptionText": null,
    "durationInDays": 134,
    "durationInWeeks": 19,
    "endDate": "2020-01-31T00:00:00.000Z",
    "private": false,
    "progressEnabled": false,
    "redOffset": -9,
    "redStart": -9,
    "redValue": 21,
    "startDate": "2019-09-18T23:00:00.000Z",
    "startValue": 0,
    "targetForecast": [],
    "targetType": ">",
    "targetValue": 30,
    "title": "A metric goal 2",
    "type": "metric",
    "unitTypeId": 5772,
    "updatedAt": "2020-03-02T23:45:00.141Z",
    "valueChange": {
      "value": 10,
      "checkInDate": "2019-09-18T23:00:00.000Z",
      "previousCheckInDate": "2019-09-18T23:00:00.000Z"
    },
    ],
    "nextCursor": 1234569
  }
{
  "data": [{
    "id": 1234567,
    "accountId": 2,
    "active": false,
    "archivedAt": "2020-03-02T23:45:00.140Z",
    "archivedBy": null,
    "cachedPercentageComplete": 0,
    "completed": false,
    "completedAt": null,
    "completedBy": null,
    "computedRAG": "R",
    "createdAt": "2019-09-19T15:11:10.140Z",
    "createdBy": 1775,
    "currentValue": 10,
    "description": "",
    "descriptionHTML": null,
    "descriptionText": null,
    "durationInDays": 134,
    "durationInWeeks": 19,
    "endDate": "2020-01-31T00:00:00.000Z",
    "private": false,
    "progressEnabled": false,
    "redOffset": -9,
    "redStart": -9,
    "redValue": 21,
    "startDate": "2019-09-18T23:00:00.000Z",
    "startValue": 0,
    "targetForecast": [],
    "targetType": ">",
    "targetValue": 30,
    "title": "A metric goal 1",
    "type": "metric",
    "unitTypeId": 5772,
    "updatedAt": "2020-03-02T23:45:00.141Z",
    "valueChange": {
      "value": 10,
      "checkInDate": "2019-09-18T23:00:00.000Z",
      "previousCheckInDate": "2019-09-18T23:00:00.000Z"
    },
    {
    "id": 1234568,
    "accountId": 2,
    "active": false,
    "archivedAt": "2020-03-02T23:45:00.140Z",
    "archivedBy": null,
    "cachedPercentageComplete": 0,
    "completed": false,
    "completedAt": null,
    "completedBy": null,
    "computedRAG": "R",
    "createdAt": "2019-09-19T15:11:10.140Z",
    "createdBy": 1775,
    "currentValue": 10,
    "description": "",
    "descriptionHTML": null,
    "descriptionText": null,
    "durationInDays": 134,
    "durationInWeeks": 19,
    "endDate": "2020-01-31T00:00:00.000Z",
    "private": false,
    "progressEnabled": false,
    "redOffset": -9,
    "redStart": -9,
    "redValue": 21,
    "startDate": "2019-09-18T23:00:00.000Z",
    "startValue": 0,
    "targetForecast": [],
    "targetType": ">",
    "targetValue": 30,
    "title": "A metric goal 2",
    "type": "metric",
    "unitTypeId": 5772,
    "updatedAt": "2020-03-02T23:45:00.141Z",
    "valueChange": {
      "value": 10,
      "checkInDate": "2019-09-18T23:00:00.000Z",
      "previousCheckInDate": "2019-09-18T23:00:00.000Z"
    },
    ],
    "nextCursor": 1234569
  }
Property Description
data The returned goals are wrapped in a data property.
nextCursor The id to use for cursor in the following request to get the next page, null if there are no more goals to load

Goal Object

Property Description
id The id of the goal.
accountId The id of the account that the goal belongs to.
active Whether the goal is active. A goal is active when it has not been archived or deleted.
archivedAt If not null the goal was archived on this date.
archivedBy If the goal has been archived, the userId of the user that archived it.
cachedPercentageComplete This stores the percentage complete of the goal as last calculated and cached.
completed Has this goal been marked as complete.
completedAt The date the goal was completed.
completedBy The userId of the user that completed the goal.
computedRAG The RAG value of this goal.
createdAt The date this goal was created.
createdBy The userId of the user that created this goal.
currentValue The current value of the goal, if it is of type metric.
description The description of the goal if any has been provided (this may be in markdown or HTML for some goals).
descriptionHTML The description converted to HTML.
descriptionText The description converted to plaintext.
durationInDays The duration from start date to end date in days.
durationInWeeks The duration from start date to end date in weeks.
endDate The end date of the goal.
private If this goal is private (Note: you can only access your own private goals).
progressEnabled If the progress feature has been enabled for this goal.
redOffset The numeric offset the red value is from the target value, if it is of type metric.
redStart The red start value, if it is of type metric.
redValue The current red value, if it is of type metric.
startDate The start date of the goal.
startValue The start value of the goal, if it is of type metric.
targetForecast An array of forecast values and dates between the start and end date.
targetType With <, > or = to indicate whether the target value is descending, increasing or remaining the same from start to end date, if it is of type metric.
targetValue The target value for the goal, if it is of type metric.
title The title of the goal
type The type of the goal objective, metric or milestone
unitTypeId The id of the unit type for this goal, if it is of type metric.
updatedAt The date the goal was last edited.
valueChange An object of value, checkInDate, previousCheckInDate giving details of the last check in

Get a Goal

Get information about a particular goal.

HTTP Request

Get the specified goal

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID> \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the user from.
GOAL_ID The id of the goal you would like to get

HTTP Response

Response

{
  "data": {
    "id": 1234567,
    "accountId": 2,
    "active": false,
    "archivedAt": "2020-03-02T23:45:00.140Z",
    "archivedBy": null,
    "cachedPercentageComplete": 0,
    "completed": false,
    "completedAt": null,
    "completedBy": null,
    "computedRAG": "R",
    "createdAt": "2019-09-19T15:11:10.140Z",
    "createdBy": 1775,
    "currentValue": 10,
    "description": "",
    "descriptionHTML": null,
    "descriptionText": null,
    "durationInDays": 134,
    "durationInWeeks": 19,
    "endDate": "2020-01-31T00:00:00.000Z",
    "private": false,
    "progressEnabled": false,
    "redOffset": -9,
    "redStart": -9,
    "redValue": 21,
    "startDate": "2019-09-18T23:00:00.000Z",
    "startValue": 0,
    "targetForecast": [],
    "targetType": ">",
    "targetValue": 30,
    "title": "A metric",
    "type": "metric",
    "unitTypeId": 5772,
    "updatedAt": "2020-03-02T23:45:00.141Z",
    "valueChange": {
      "value": 10,
      "checkInDate": "2019-09-18T23:00:00.000Z",
      "previousCheckInDate": "2019-09-18T23:00:00.000Z"
    },
  }
}
{
  "data": {
    "id": 1234567,
    "accountId": 2,
    "active": false,
    "archivedAt": "2020-03-02T23:45:00.140Z",
    "archivedBy": null,
    "cachedPercentageComplete": 0,
    "completed": false,
    "completedAt": null,
    "completedBy": null,
    "computedRAG": "R",
    "createdAt": "2019-09-19T15:11:10.140Z",
    "createdBy": 1775,
    "currentValue": 10,
    "description": "",
    "descriptionHTML": null,
    "descriptionText": null,
    "durationInDays": 134,
    "durationInWeeks": 19,
    "endDate": "2020-01-31T00:00:00.000Z",
    "private": false,
    "progressEnabled": false,
    "redOffset": -9,
    "redStart": -9,
    "redValue": 21,
    "startDate": "2019-09-18T23:00:00.000Z",
    "startValue": 0,
    "targetForecast": [],
    "targetType": ">",
    "targetValue": 30,
    "title": "A metric",
    "type": "metric",
    "unitTypeId": 5772,
    "updatedAt": "2020-03-02T23:45:00.141Z",
    "valueChange": {
      "value": 10,
      "checkInDate": "2019-09-18T23:00:00.000Z",
      "previousCheckInDate": "2019-09-18T23:00:00.000Z"
    },
  }

The returned goal is wrapped in a data property.

Property Description
id The id of the goal.
accountId The id of the account that the goal belongs to.
active Whether the goal is active. A goal is active when it has not been archived or deleted.
archivedAt If not null the goal was archived on this date.
archivedBy If the goal has been archived, the userId of the user that archived it.
cachedPercentageComplete This stores the percentage complete of the goal as last calculated and cached.
completed Has this goal been marked as complete.
completedAt The date the goal was completed.
completedBy The userId of the user that completed the goal.
computedRAG The RAG value of this goal.
createdAt The date this goal was created.
createdBy The userId of the user that created this goal.
currentValue The current value of the goal, if it is of type metric.
description The description of the goal if any has been provided (this may be in markdown or HTML for some goals).
descriptionHTML The description converted to HTML.
descriptionText The description converted to plaintext.
durationInDays The duration from start date to end date in days.
durationInWeeks The duration from start date to end date in weeks.
endDate The end date of the goal.
private If this goal is private (Note: you can only access your own private goals).
progressEnabled If the progress feature has been enabled for this goal.
redOffset The numeric offset the red value is from the target value, if it is of type metric.
redStart The red start value, if it is of type metric.
redValue The current red value, if it is of type metric.
startDate The start date of the goal.
startValue The start value of the goal, if it is of type metric.
targetForecast An array of forecast values and dates between the start and end date.
targetType With <, > or = to indicate whether the target value is descending, increasing or remaining the same from start to end date, if it is of type metric.
targetValue The target value for the goal, if it is of type metric.
title The title of the goal
type The type of the goal objective, metric or milestone
unitTypeId The id of the unit type for this goal, if it is of type metric.
updatedAt The date the goal was last edited.
valueChange An object of value, checkInDate, previousCheckInDate giving details of the last check in

Get Permissions

Get information about what permissions the currently authenticated user has over a particular goal.

HTTP Request

Get the permissions for a goal

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/permissions", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/permissions \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/permissions

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the user from.
GOAL_ID The id of the goal you would like to get.

HTTP Response

Response

{
  "data": {
    "canEdit": true,
    "canCheckIn": true,
    "canAutomate": false,
    "canView": true
  }
}
{
  "data": {
    "canEdit": true,
    "canCheckIn": true,
    "canAutomate": false,
    "canView": true
  }
}

The returned goal permissions is wrapped in a data property.

Property Description
canEdit Whether the requesting user can edit this goal.
canCheckIn Whether the goal supports check-ins and whether the requesting user can check-in on this goal.
canAutomate Whether the goal supports automation.
canView Whether the requesting user can view this goal, this will always be true as you can only access the permissions of goals you can view.

Check-in

Check-in on a metric goal in your account.

HTTP Request

Check in on a goal

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/check-in", {
  "method": "POST",
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
    "authorization": "Bearer <ACCESS_TOKEN>"
  },
  "body": {
    "value": "<VALUE>",
    "sourceUpdatedAt": "<SOURCE_UPDATED_AT>",
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request POST \
  --url https://api-public.dev.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/check-in \
  --header 'authorization: Bearer <ACCESS_TOKEN>' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data value=<VALUE> \
  --data sourceUpdatedAt=<SOURCE_UPDATED_AT>

POST https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/check-in

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the user from.
GOAL_ID The id of the goal you would like to get

POST Parameters

Parameter Description
VALUE The numeric (whole or decimal) value without unit type you would like to check in on a goal.
SOURCE_UPDATED_AT The date the value changed. This is used to identify whether the value has changed. i.e. if the sourceUpdatedAt is the same as the last check-in's sourceUpdatedAt, the check-in is ignored.

HTTP Response

If the check-in was a success, the status of the response is 200

Get all Check-ins for a Goal

Get all check-ins for a goal.

HTTP Request

Get all check-ins for a goal

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/check-ins?cursor=1234567&limit=10", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url 'https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/check-ins?cursor=1234567&limit=10' \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

GET https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/check-ins

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the check-ins from.
GOAL_ID The id of the goal you would like to get

Query Parameters

Parameter Description
limit Limit the number of results returned. Default: 10 (Valid range 1-100)
cursor The id of the check-in to select from, the nextCursor value is returned by each call of the API allowing you to page through the results.

HTTP Response

Response

{
  "data": [
    {
      "id": 377932,
      "value": null,
      "goalId": 46254,
      "userId": 42,
      "eventType": "checkin",
      "status": "G",
      "eventDate": "2020-03-25T14:59:56.491Z",
      "dataSourcedAt": null,
      "percentageComplete": null,
      "deletedAt": null,
      "createdAt": "2020-03-25T15:00:04.059Z",
      "updatedAt": "2020-03-25T15:00:04.059Z",
      "message": "All good",
      "messageHTML": "All good",
      "messageText": "All good"
    }
  ],
  "nextCursor": null
}
{
  "data": [
    {
      "id": 377932,
      "value": null,
      "goalId": 46254,
      "userId": 42,
      "eventType": "checkin",
      "status": "G",
      "eventDate": "2020-03-25T14:59:56.491Z",
      "dataSourcedAt": null,
      "percentageComplete": null,
      "deletedAt": null,
      "createdAt": "2020-03-25T15:00:04.059Z",
      "updatedAt": "2020-03-25T15:00:04.059Z",
      "message": "All good",
      "messageHTML": "All good",
      "messageText": "All good"
    }
  ],
  "nextCursor": null
}
Property Description
data The returned check-ins are wrapped in a data property.
nextCursor The id to use for cursor in the following request to get the next page, null if there are no more check-ins to load

Check In Object

Property Description
id The id of the check-in.
value The value that was submitted for this check in.
goalId The id of the goal this check-in is associated with.
userId The id of the user that submitted this check-in.
eventType This will be checkin.
status The R (red), A (amber) or G (green) RAG status for this check-in.
eventDate The date of this check-in.
dataSourcedAt If created by an automated check-in, this is the date that source was updated.
percentageComplete The percentage complete for this check-in.
createdAt The date this check-in was created.
updatedAt The date this check-in was last updated.

Initiatives

You can use the API to get information about any initiatives associated with a goal.

Get All Initiatives For A Goal

Get a list of all initiatives for a goal within an account

HTTP Request

Get all initiatives for a goal

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/initiatives", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url 'https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/initiatives' \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<GOAL_ID>/initiatives

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the user from.
GOAL_ID The id of the goal you would like to fetch initiatives for

HTTP Response

Response

{
  "data": [
    {
      "id": 46325,
      "accountId": 2,
      "archivedAt": null,
      "archivedBy": null,
      "cachedPercentageComplete": 0,
      "completed": false,
      "completedAt": null,
      "completedBy": null,
      "computedRAG": "G",
      "createdAt": "2020-02-04T11:19:13.852Z",
      "createdBy": 6243,
      "deletedAt": null,
      "description": "The initiatives description",
      "descriptionHTML": "<p>The initiatives description</p>\n",
      "descriptionText": "The initiatives description",
      "durationInDays": 25,
      "durationInWeeks": 3,
      "endDate": "2020-02-29T00:00:00.000Z",
      "progressEnabled": true,
      "startDate": "2020-02-04T00:00:00.000Z",
      "title": "An Initiative",
      "updatedAt": "2020-02-28T16:37:01.052Z",
      "updatedBy": null
    },
    {
      "id": 46326,
      "accountId": 2,
      "archivedAt": null,
      "archivedBy": null,
      "cachedPercentageComplete": 0,
      "completed": false,
      "completedAt": null,
      "completedBy": null,
      "computedRAG": "G",
      "createdAt": "2020-02-04T11:19:13.852Z",
      "createdBy": 6243,
      "deletedAt": null,
      "description": "The other initiatives description",
      "descriptionHTML": "<p>The other initiatives description</p>\n",
      "descriptionText": "The other initiatives description",
      "durationInDays": 25,
      "durationInWeeks": 3,
      "endDate": "2020-02-29T00:00:00.000Z",
      "progressEnabled": true,
      "startDate": "2020-02-04T00:00:00.000Z",
      "title": "Another Initiative",
      "updatedAt": "2020-02-28T16:37:01.052Z",
      "updatedBy": null
    }
  ]
}
{
  "data": [
    {
      "id": 46325,
      "accountId": 2,
      "archivedAt": null,
      "archivedBy": null,
      "cachedPercentageComplete": 0,
      "completed": false,
      "completedAt": null,
      "completedBy": null,
      "computedRAG": "G",
      "createdAt": "2020-02-04T11:19:13.852Z",
      "createdBy": 6243,
      "deletedAt": null,
      "description": "The initiatives description",
      "descriptionHTML": "<p>The initiatives description</p>\n",
      "descriptionText": "The initiatives description",
      "durationInDays": 25,
      "durationInWeeks": 3,
      "endDate": "2020-02-29T00:00:00.000Z",
      "progressEnabled": true,
      "startDate": "2020-02-04T00:00:00.000Z",
      "title": "An Initiative",
      "updatedAt": "2020-02-28T16:37:01.052Z",
      "updatedBy": null
    },
    {
      "id": 46326,
      "accountId": 2,
      "archivedAt": null,
      "archivedBy": null,
      "cachedPercentageComplete": 0,
      "completed": false,
      "completedAt": null,
      "completedBy": null,
      "computedRAG": "G",
      "createdAt": "2020-02-04T11:19:13.852Z",
      "createdBy": 6243,
      "deletedAt": null,
      "description": "The other initiatives description",
      "descriptionHTML": "<p>The other initiatives description</p>\n",
      "descriptionText": "The other initiatives description",
      "durationInDays": 25,
      "durationInWeeks": 3,
      "endDate": "2020-02-29T00:00:00.000Z",
      "progressEnabled": true,
      "startDate": "2020-02-04T00:00:00.000Z",
      "title": "Another Initiative",
      "updatedAt": "2020-02-28T16:37:01.052Z",
      "updatedBy": null
    }
  ]
}

Initiative Object

Property Description
id The id of the goal.
accountId The id of the account that the goal belongs to.
archivedAt If not null the goal was archived on this date.
archivedBy If the goal has been archived, the userId of the user that archived it.
cachedPercentageComplete This stores the percentage complete of the goal as last calculated and cached.
completed Has this goal been marked as complete.
completedAt The date the goal was completed.
completedBy The userId of the user that completed the goal.
computedRAG The RAG value of this goal.
createdAt The date this goal was created.
createdBy The userId of the user that created this goal.
description The description of the goal if any has been provided (this may be in markdown or HTML for some goals).
descriptionHTML The description converted to HTML.
descriptionText The description converted to plaintext.
durationInDays The duration from start date to end date in days.
durationInWeeks The duration from start date to end date in weeks.
endDate The end date of the goal.
progressEnabled If the progress feature has been enabled for this goal.
redOffset The numeric offset the red value is from the target value, if it is of type metric.
startDate The start date of the goal.
title The title of the goal
updatedAt The date the goal was last edited.

Get all Check-ins for a Initiative

Get all check-ins for a initiative.

HTTP Request

Get all check-ins for a initiative

fetch("https://api.just3things.com/v1/<ACCOUNT_KEY>/initiatives/<INITIATIVE_ID>/check-ins?cursor=1234567&limit=10", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer <ACCESS_TOKEN>"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.log(err);
});
curl --request GET \
  --url 'https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<INITIATIVE_ID>/check-ins?cursor=1234567&limit=10' \
  --header 'authorization: Bearer <ACCESS_TOKEN>'

GET https://api.just3things.com/v1/<ACCOUNT_KEY>/goals/<INITIATIVE_ID>/check-ins

URL Parameters

Parameter Description
ACCOUNT_KEY The accountKey for the account to select the check-ins from.
INITIATIVE_ID The id of the initiative you would like to get

Query Parameters

Parameter Description
limit Limit the number of results returned. Default: 10 (Valid range 1-100)
cursor The id of the check-in to select from, the nextCursor value is returned by each call of the API allowing you to page through the results.

HTTP Response

Response

{
  "data": [
    {
      "id": 377932,
      "value": null,
      "goalId": 46254,
      "userId": 42,
      "eventType": "checkin",
      "status": "G",
      "eventDate": "2020-03-25T14:59:56.491Z",
      "dataSourcedAt": null,
      "percentageComplete": null,
      "deletedAt": null,
      "createdAt": "2020-03-25T15:00:04.059Z",
      "updatedAt": "2020-03-25T15:00:04.059Z",
      "message": "All good",
      "messageHTML": "All good",
      "messageText": "All good"
    }
  ],
  "nextCursor": null
}
{
  "data": [
    {
      "id": 377932,
      "value": null,
      "goalId": 46254,
      "userId": 42,
      "eventType": "checkin",
      "status": "G",
      "eventDate": "2020-03-25T14:59:56.491Z",
      "dataSourcedAt": null,
      "percentageComplete": null,
      "deletedAt": null,
      "createdAt": "2020-03-25T15:00:04.059Z",
      "updatedAt": "2020-03-25T15:00:04.059Z",
      "message": "All good",
      "messageHTML": "All good",
      "messageText": "All good"
    }
  ],
  "nextCursor": null
}
Property Description
data The returned check-ins are wrapped in a data property.
nextCursor The id to use for cursor in the following request to get the next page, null if there are no more check-ins to load

Check In Object

Property Description
id The id of the check-in.
value The value that was submitted for this check in.
goalId The id of the initiative this check-in is associated with.
userId The id of the user that submitted this check-in.
eventType This will be checkin.
status The R (red), A (amber) or G (green) RAG status for this check-in.
eventDate The date of this check-in.
dataSourcedAt If created by an automated check-in, this is the date that source was updated.
percentageComplete The percentage complete for this check-in.
createdAt The date this check-in was created.
updatedAt The date this check-in was last updated.

Errors

HTTP Response

All errors are wrapped in an error property

Error codes

The Just3Things API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your authorization details are incorrect.
403 Forbidden -- You are not permitted to access the requested resource.
404 Not Found -- The requested resource was not found.
500 Internal Server Error -- We had a problem with our server. Please try again later and contact us if the problem persists.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.