REST, OAuth 2.0, and JSON

This page tells you how to send requests to the ClearPoint API. It tells you about the structure of a request, the authentication, and the JSON data format.

Read Start here first. The difference between Edit fields and Update fields on that page tells you the endpoint that you need.

The structure of the API

The ClearPoint API is a REST API and uses HTTPS. Send all requests to this address:

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

All endpoints have the same structure. The address of a collection gives all the items of that type that the user can access. If you add an ID to the address, you get one record. An address with more than one part shows a relation between elements:

GET /scorecards                                 All scorecards that you can access
GET /scorecards/{scorecardId}                   One scorecard
GET /scorecards/{scorecardId}/measures          The measures in that scorecard
GET /objectives/{objectiveId}/links             The elements with a link to that objective
POST /measures/{measureId}/measureData          Write period data for a measure

All requests and all responses use application/json.

How to authenticate

The API has two authentication methods:

• OAuth 2.0 — for an application that a person operates. The person signs in to ClearPoint in a browser.
• API keys — for an integration that operates without a person. This method does not need a browser.

Select the method by the type of integration, not by the endpoints that you call. Both methods give access to the same endpoints.

OAuth 2.0 for interactive applications

The API uses OAuth 2.0 with the authorization code grant and PKCE. Your client sends the user to ClearPoint. The user signs in and gives approval. Your client then changes the code into an access token.

The two addresses are for two different steps. The user signs in at the authorization URL. Your client then sends the code to the token URL and gets an access token. Do not use the same address for both steps.

Send the token in this header with each request:

Authorization: Bearer <access_token>

An access token has a limited life. Get a new token with the refresh token. Do not ask the user to sign in for each operation. Keep all tokens in a safe location.

For an example configuration in a client, refer to How to use Postman.

API keys for integrations without a person

Use ClearPoint API keys for a scheduled integration or for a server-to-server integration. This method has no sign-in step and no browser step.

Make the keys in the ClearPoint application. Then send them in two headers with each request:

AccessKey: <your access key>
SecretKey: <your secret key>

Do not use the Authorization header with this method.

These keys are the same keys as the keys for the MCP server. One pair gives access to both.

A key pair belongs to one ClearPoint user. The integration gets the permissions of that user.

If that user gets a different role, you can change the user of the key pair. Set userId on the key pair with the API, or change the user in the ClearPoint application. You do not have to make a new pair. The keys stay the same. Your integration continues to operate.

🚧

Make a user account for the integration

Do not use the account of a person for an integration. If that person leaves your organization or gets a different role, the integration stops. Make a ClearPoint user account for the integration and give it the minimum permissions that it needs.

A key pair can have an expiry date. Record that date and make a new pair before the date. Keep the keys in a safe location. Do not put them in your software code. If a key is not safe, make a new pair in the application.

📘

Scopes and permissions

ClearPoint does not use OAuth scopes to limit access. Access comes from the ClearPoint permissions, not from the request. To limit what an integration can do, control the permissions of the account that it uses.

The JSON data format

The structure of an element

All elements have the same basic fields. Each element has an object type and an objectId. Together, these two values identify the element.

{
  "scorecardId": 123456,
  "object": "scorecard",
  "objectId": 123456,
  "parentId": null,
  "name": "Citywide Strategic Plan",
  "locked": false,
  "active": true,
  "archived": false,
  "sortOrder": 2,
  "createdDate": "2011-06-15T14:13:40.723Z",
  "createdBy": null,
  "updatedDate": "2023-06-09T17:42:02.277Z",
  "updatedBy": 86793,
  "access": "Administrator"
}

These fields are the most important:

• object and objectId — the type and the ID of the element. Keep both values when you make a reference to an element.
• access — the permission level of the user for this element. The usual values are Browser, Updater, Editor, Scorecard Admin, and Administrator. The field can also give No Access and Limited. For the permissions of each role, refer to ClearPoint Strategy User Roles Explained.
• active and archived — if archived is true, the application does not show the element. If active is false, the element has a soft delete. Use these two fields as a filter when you make a report.
• parentId — the ID of the parent scorecard, if the scorecard is in a structure with more than one level.

Dates

A date and time value uses the ISO 8601 format in UTC, for example 2023-06-09T17:42:02.277Z. A date value has the format YYYY-MM-DD. Milestones use date values for the start and the end.

Custom fields

The API gives custom fields as an object with keys, not as a list. Each key has the format customNNN, where NNN is the ID of the field. Each value contains the name of the field, the fieldType, and the value.

These are the usual field types: text, number, date, html, link, select, and grid.

Your users know the field by its name, but the ID does not change. Use the ID in your integration.

Reporting periods

If you do not specify a period, a read endpoint uses the default period of the scorecard. But some endpoints need a period. These endpoints give the error 400 if the periodId is not there:

GET /scorecards/{scorecardId}/fields?periodId={periodId}
GET /layouts/{object}/reports/{layoutId}?periodId={periodId}

To get the periods, use GET /periods. To get the reporting frequencies, use GET /periodGroups. Then select the correct period. Do not use the most recent period without a check.

Limits

ClearPoint records the use of the API. This record includes each request through the REST API, the MCP server, and Zapier. It does not include the operations of a person who works in the application.

ClearPoint does not apply a fixed limit to the number of requests at this time. But make your integration ready for a limit:

• Send only the requests that your integration needs.
• Use an endpoint for a collection in place of many single requests.
• Read the status code of each response. If the status is 429, stop and send the request again later.
• Increase the time between the retries after each unsuccessful retry.

ClearPoint can add limits later. An integration with these controls continues to operate.

Errors

If you get the error 403 immediately after a correct sign-in, the usual cause is the permission level. Examine the access of that account for the applicable scorecard first.

Reference

You can find the OpenAPI 3.1 specification at apidoc.clearpointstrategy.com/openapi.json. This specification is the correct reference for each endpoint, each request, and each response. You can import it into Postman or into a code generator.