--- updatedAt: 2026-09-17T16:00:11.000Z agentTools: projectIndex: https://developer.clearpointstrategy.com/llms.txt --- # How to use Postman Import the ClearPoint OpenAPI specification, set up OAuth 2.0, and send authenticated requests before you write software code. 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](https://www.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 1. In Postman, select **Import**. 2. Select the **Link** tab. 3. Enter this address: ``` https://apidoc.clearpointstrategy.com/openapi.json ``` 4. Select **Continue**. 5. 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. 1. Select the collection, then open the **Authorization** tab. 2. Set **Type** to `OAuth 2.0`. 3. 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. 4. Select **Get New Access Token**. 5. Enter your ClearPoint user name and password, then give approval to the request. 6. Select **Use Token**. Postman adds the header `Authorization: Bearer ` 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. 1. Make an API key pair in the ClearPoint application. 2. In Postman, select the collection, then open the **Authorization** tab. 3. Set **Type** to `No Auth`. 4. 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 ``` ```json { "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} ``` ```json { "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](https://developer.clearpointstrategy.com/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](https://developer.clearpointstrategy.com/docs/rest-oauth-and-json) — the JSON data format and the errors * [API Reference](https://developer.clearpointstrategy.com/reference/) — each endpoint and each schema * Send the collection to your team. All the members then use the same requests.