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 or XML 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 XML or 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 either XML or 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 either XML or 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 XML or JSON. If you fail to set your Content-Type to either application/xml or 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

For development purposes we also have a publicly available API test application that will allow you to send test requests to verify your call is correct. You can access the API test tool here:

https://api.resultsscorecard.com/test

Another handy tool is RequestBin. You could create a RequestBin and send your request to them instead of us, 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