Start here

The ClearPoint API gives your software access to your ClearPoint data. You can read and write scorecards, objectives, measures, initiatives, and their reporting data.

Use the API to do these tasks:

• Send data into ClearPoint from a different system.
• Get ClearPoint data for a data warehouse or a report tool.
• Remove manual data entry from your reporting cycle.

The Enterprise plan includes access to the API. If you do not know your plan, speak to your ClearPoint account manager.

Integration methods

ClearPoint has three integration methods. Many organizations use more than one method.

This part of the documentation tells you about the REST API. For the other two methods, refer to Model Context Protocol (MCP) server and How to use Zapier.

Before you start

You must have these three items:

• An organization with the Enterprise plan.
• A ClearPoint user account with enough permission for the applicable scorecards. The API uses the same permissions as the application. A user with Browser permission cannot write data.
• The scorecardId of the applicable scorecard. You can see this ID in the address of the application page.

Data concepts

Four concepts cause most of the questions from new users of the API.

Elements

Each object in ClearPoint is an element. Each element has an object type and an objectId. Together, these two values identify the element.

The default element types are Scorecard, Category, Objective, Measure, Initiative, Milestone, Action Item, and Risk. Each organization can change these names in the application. Your users can know the elements by different names.

The API always uses the default names. Make a list of your names and the related default names before you start.

Scorecards and access

A scorecard contains the other elements. Each element is in a minimum of one scorecard. You can also link elements between scorecards. One measure can show in more than one scorecard.

Permissions apply to each scorecard. An API call gives only the data that the user can see. Each element in a response has an access field. This field shows the permission level of the user. The usual values are Browser, Updater, Editor, Scorecard Admin, and Administrator. These are the same user roles as in the application. The field can also give No Access and Limited.

Edit fields and Update fields

This is the most important difference in the ClearPoint data model.

• Edit fields do not change often. Examples are the name, the definition, the owner, and the evaluation rules of a measure. These fields are part of the element. To change them, use PUT /measures/{measureId}.
• Update fields change in each reporting period. Examples are actuals, targets, statuses, and period notes. These fields apply to one reporting period. To change them, use an endpoint for periods, for example POST /measures/{measureId}/measureData.

A change to the name of a KPI and an entry of the result for this quarter are two different operations. They use two different endpoints.

Reporting periods

ClearPoint keeps performance data for each period. Much of the data applies to one period only.

If you do not specify a period, most read endpoints use the default period of the scorecard. But some endpoints need a periodId. If the periodId is not there, these endpoints give the error 400.

To get the periods, use GET /periods. To get the reporting frequencies, use GET /periodGroups.

How to make your first call

You can send requests from the developer portal. After you sign in, the portal uses your own OAuth 2.0 token. The requests then operate on live data.

1. Select Login at the top right of the page.
2. Enter your ClearPoint user name and password.
3. Open Get My Profile in the API Reference.
4. Select Try It!.

A correct response contains your own user record. This response shows two things: the authentication is correct, and your account has access to the API.

📘

How to authenticate from your own software

The portal does the OAuth 2.0 procedure for you. Your own software uses one of two methods. Use OAuth 2.0 for an application that a person operates. Use ClearPoint API keys for an integration that operates without a person. Refer to REST, OAuth 2.0, and JSON. For an example with a client, refer to How to use Postman.

The structure of the API

Send all requests to this address:

https://app.clearpointstrategy.com/api/v1

The API Reference shows the endpoints for each element type. The API uses four HTTP methods.

A GET request gets a collection or one item from a collection. GET /scorecards gets all the scorecards that the user can access. GET /scorecards/{scorecardId} gets one scorecard.

You can find the OpenAPI 3.0 specification at apidoc.clearpointstrategy.com/openapi.json. You can import this specification into Postman, Insomnia, or a code generator.

What to do next

• Uses for the ClearPoint API — the usual integrations and the conditions that apply to them
• REST, OAuth 2.0, and JSON — authentication and the JSON data format
• How to use Postman — how to import the specification and send authenticated requests
• Model Context Protocol (MCP) server — how to connect an AI client to ClearPoint

Support

For questions about access, authentication, or integration, send a message to [email protected].