API: Overview and Authentication

Introduction to Scorecard's API

The Clear Impact Scorecard API enables you to access and interact with our system programmatically from other applications. 

With API calls, you can access and interact with:

• Scorecards and containers
• Results and programs
• Indicators, performance measures, or other measures
• Tags
• Actions
• Users
• Imported and exported data values

An API key is needed for these connections, which can be obtained or generated by instance admin users. The API Authentication is implemented as an API Key sent with each payload over SSL (HTTPS). Your API login credentials are not the same as the credentials you use to log into your Scorecard instance. You must obtain your obtain your API key separately.

In addition to the API key, all API requests also require an instance site code. This can be found at the top right of any Scorecard window.

Note: To learn more about testing your API connect, and environment options, see the Development Tips article.

The API is grouped into several modules that each implement List, Add, Get Details, Update, and Delete operations for a particular type of scorecard object.

Authentication is implemented using an API Key included in each JSON payload over SSL (https).

Note: If you’re not well-versed in API calls, you’ll likely need to enlist the skills of a web developer or programmer.

For security reasons, all API handlers are decorated with [HttpPost] attribute, forcing the API user to invoke the API using HTTP POST method.

All data submitted by the API client is sent as a JSON payload of the POST request. This payload consists of some common data, such as the sitecode and API key, and some API specific data, for example an ID of a database object.

URL

The URL for API requests includes the resource URI:

https://api.resultsscorecard.com/<resource URI>

Response Data

Response data is sent as JSON, depending on the type of data requested (HTTP Content-Type header) or the type specified as being accepted (HTTP Accept header).

Response codes are sent via the normal HTTP Response Code, and are documented separately for each resource.

Request Data

POST request data may be formatted as JSON. For best results, you should set your HTTP Content-Type request header accordingly, although you may also specify your format by appending .xml or .json extensions on to the resource URI.

Note that Clear Impact Scorecard does not accept POST data sent as query params or form encoded data – data must be sent as either JSON. If you fail to set your Content-Type to application/json, your request may fail due to triggering of forgery protection mechanisms.

Example JSON Request Formatting

Note the content-type header and the request parameters entered in the body of the request.

Debugging

A handy tool that users can use for debugging is RequestBin. You can create a RequestBin and send your request to see visually what it is you're sending, if you're not sure.

For more development information check out our Development Tips page.

API Excluded Data Types