How to use Postman

Postman is the quickest method to examine the ClearPoint API. Use it to test your requests before you write software code.

When you import the OpenAPI specification, Postman makes a collection of all the ClearPoint endpoints. When you set up OAuth 2.0 one time, you can send authenticated requests to live data.

Before you start

You must have these three items:

Postman on your computer. You can get it from postman.com/downloads.
A ClearPoint account in an organization with the Enterprise plan.
Enough permission for the scorecards that you want to read or write.

How to import the OpenAPI specification

In Postman, select Import.
Select the Link tab.

Enter this address:

https://apidoc.clearpointstrategy.com/openapi.json

Select Continue.
Examine the preview, then select Import.

Postman makes a collection with a folder for each element type. The collection contains each endpoint, each parameter, and an example request from the specification.

Import the specification again at regular times. This procedure gets the changes to the specification.

How to set up OAuth 2.0

ClearPoint uses the authorization code grant with PKCE. Set up the authentication one time for the collection. All the requests in the collection then use it.

Select the collection, then open the Authorization tab.
Set Type to OAuth 2.0.
Give these values:

Field	Value
Add auth data to	Request Headers
Header Prefix	`Bearer`
Grant Type	Authorization Code (With PKCE)
Callback URL	`https://oauth.pstmn.io/v1/callback`
Auth URL	`https://app.clearpointstrategy.com/oauth2/auth`
Access Token URL	`https://app.clearpointstrategy.com/oauth2/token`
Client ID	Any name, for example `postman`
Client Secret	Keep this field empty. PKCE does not need a client secret.
Scope	Keep this field empty. Access comes from your ClearPoint permissions.
Client Authentication	Send client credentials in body

The Auth URL and the Access Token URL are two different addresses. The Auth URL is for the sign-in step. The Access Token URL is for the token step.

Select Get New Access Token.
Enter your ClearPoint user name and password, then give approval to the request.
Select Use Token.

Postman adds the header Authorization: Bearer <token> to the requests in the collection.

📘
Do a test before you write software code
Send GET /profile. A correct response contains your own user record.

An access token has a limited life. If your requests give the error 401, get a new token in the same tab.

A quicker method: API keys

For a test, API keys are quicker than OAuth 2.0. This method has no sign-in step.

Make an API key pair in the ClearPoint application.
In Postman, select the collection, then open the Authorization tab.
Set Type to No Auth.
Open the Headers tab and add these two headers:

Key	Value
`AccessKey`	Your access key
`SecretKey`	Your secret key

The keys do not have a short life, so you do not get a new token during a test.

🚧
Do not send a collection with your keys in it
If you send the collection to your team, remove the keys first. Keep them in a Postman environment variable or in a vault.

Use OAuth 2.0 when you must test the sign-in procedure of a user. Use API keys when you must test the endpoints.

Example requests

These examples use the address https://app.clearpointstrategy.com/api/v1. Set up the authentication before you send them.

How to make a measure

POST /measures

{
  "name": "Revenue Growth",
  "scorecardId": 1,
  "ownerId": 12345,
  "collaborators": [12346, 12347],
  "hiddenPeriods": [],
  "tags": [1, 2, 3],
  "externalApplication": "FinanceApp",
  "externalObject": "RevenueTable",
  "externalObjectId": "RT123"
}

The fields externalApplication, externalObject, and externalObjectId keep the ID of the element in your other system. Your integration can then find the element again. You do not need a separate list of the related IDs.

How to change a measure

A change to a measure changes only the configuration: the name, the owner, the definition, and the tags. It does not change the reporting data.

PUT /measures/{measureId}

{
  "name": "Revenue Growth (Net)",
  "scorecardId": 2,
  "ownerId": 12348,
  "collaborators": [12349],
  "tags": [4, 5]
}

How to write measure data for a period

Write the reporting values with the endpoint for periods. These values are the actuals, the targets, and the period notes. Do not use PUT for them.

POST /measures/{measureId}/measureData

First, get the period IDs with GET /periods. Then refer to the API Reference for the request. The fields are different for each account, because they include your measure series and your custom fields.

How to delete a measure

DELETE /measures/{measureId}

This request does not need content. A delete operation is a soft delete: it removes the element from the application, but ClearPoint keeps the record.

Problems and solutions

Problem	Usual cause
All requests give the error `401`	The token has no more life, or Postman did not add it to the request. Get a new token.
Read requests are correct, but write requests give the error `403`	The account does not have Editor or Administrator permission for that scorecard.
The error `400` shows `periodId`	The endpoint needs a period. Add `?periodId={id}` to the address.
The error `404` shows for a correct ID	The element is in a scorecard that the account cannot access, or the element has a soft delete.
The authorization window does not come back	The callback URL is not correct. Make sure that it is the same, with `https://`.

What to do next

REST, OAuth 2.0, and JSON — the JSON data format and the errors
API Reference — each endpoint and each schema
Send the collection to your team. All the members then use the same requests.