Getting started with the ClearPoint API

The ClearPoint API allows clients to integrate their other applications and data sources with their ClearPoint account.  ClearPoint clients on the Enterprise Plan are able to access the ClearPoint API.  Our documentation for the API can be used to familiarize yourself with everything that is possible and get you off to a quick start when integrating with ClearPoint or making an integration of your own.

Instructions

1. Get your API Keys

In order to use the API, you’ll first need to create your personal API Keys.  These are available for Enterprise plans and can be accessed from Admin Options.  Check out this help article for more details on where to find them.

2. Learn some key ClearPoint concepts

Edit vs. Update Fields: ClearPoint is reporting software.  Clients use it to report on their progress over time, such as every month or every quarter.  Some fields need to remain consistent over time, like a measure definition or owner, while other fields need new data every reporting period, such as a status or monthly analysis.  Fields that stay the same over time are known as Edit fields whereas fields that are tied to reporting periods and can contain a new value every period are Update fields.

Scorecards: Scorecards can be thought of as folders for the reporting structure.  Other elements, such as Objectives and Measures, live inside the scorecard and can be linked together to show how they are related.  Every element lives in at least one scorecard, but may also exist in others due to links between elements.  You must have access to a scorecard where the element lives in order to access that element over the API.

Default Element Names: ClearPoint can be customized to meet any reporting structure by customizing the names of the default reporting elements.  The default element names are Scorecard, Category, Objective, Measure, Initiative, Milestone, Action Item, and Risk.  These are the element names you will see throughout the API documentation.  It is important to familiarize yourself with the terminology used by your organization and match that to the corresponding default element in ClearPoint.  Check out this help article to match your strategic elements to their default names found in the API documentation.   It is important to note that not every element is used by every organization, so some may be hidden in your account.

3. Get familiar with the ClearPoint API structure

ClearPoint’s API Documentation is organized by element, such as scorecards.  All available methods and endpoints are grouped by element.  The API documentation page is not intended to serve as your GUI for interacting with the API.  Instead, use it as a guide for identifying the calls needed to perform a specific action.  Another good resource is your browser’s developer tools. When logged into ClearPoint you can make a change and then watch the network section of the developer tools for information on how the call should be structured.

ClearPoint’s API exposes the four standard methods for interacting with REST services: POST (create), GET (read), PUT (update/replace), and DELETE (delete). GET requests can be made to either read a collection or a specific member. For example, GET /scorecards will retrieve all scorecards for which you have access and GET /scorecards/{scorecardId} will retrieve information for a specific scorecard.

Requests should be configured using standard HTTPS protocol.  All payloads should be formatted in JSON and all response payloads will be returned in JSON. (wording, extra spaces, clarity)

4. Practice on a few common API calls

For practicing or testing API calls, we recommend using a tool like Postman to make requests against the demo server: https://demo.clearpointstrategy.com/api/v1/.  The demo database is overwritten every night at 1 AM by data in your production database, making it a great place to practice.  When you are ready to use the real thing, the production URL is https://app.clearpointstrategy.com/api/v1/.

Using your API Keys in the request headers, try out some of these common actions:

1. GET /scorecards
2. GET /scorecards/{scorecardId}
3. POST /measures
   • In the request body, specify the “scorecardId” retrieved in the previous step.  Also provide a “name.”
4. GET /measures/{measureId}
   • Write down the seriesId for one of your series
5. GET /periods
   1. Write down the periodId
6. POST /update
   • If you plan on using the API to make actual changes to your data, this call will be your best friend.
   • In this example, we’ll make updates to the measure created before by changing its name, adding in new measure data to the measure series, and providing analysis for a recent period

{
  "edits":[
            {
              "object":"measure",
              "objectId":{objectId},
              "fields":{
                "name":"<Insert name change here>",
                "measureData":[
                  {
                    "periodId":{periodId},
                    "series{seriesId}":<Insert a numeric value>
                  }
                ]
              }
           }
        ],
"updates":[
            {
              "object":"measure",
              "objectId":{objectId},
              "periodId":{periodId},
              "fields":{
                "analysis":"<Insert sample analysis here>"
              }
           }
        ]
}