Our goal metrics API is only available on paid Koan plans. Learn more about our pricing here.

Prerequisites

Make sure you've read our guide on getting started with the Goal Metrics API. You'll need to have a goal with API integration enabled in order to proceed.
This guide assumes some general knowledge of how to work with a web API. If you're not familiar with this, we suggest you try out our Zapier guide instead.

Building your Custom API Integration

The API URL you got from the goal edit page can be used through a standard HTTP POST request. For example, here's how you'd use curl to set the latest value of your goal's metric to 250:

curl \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{ "action": "set", "value" : 250 }' \
  <YOUR_INTEGRATION_URL_HERE>

The API currently supports three actions:

set : Sets the goal's value to the value field provided.
add : Sets the goal's value to the sum of its current value and the value field provided.
subtract Sets the goal's value to the difference of its current value and the value field provided.

For example, if your goal's current value is 15 and you want to add 5 to it, you could do the following:

curl \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{ "action": "add", "value" : 5 }' \
  <YOUR_INTEGRATION_URL_HERE>

API Reference

The API URL accepts a JSON blob containing the following fields:

action: string (required): One of set, add, or subtract .
value: number | string (required): If a string is passed in, it will be converted to a number. Some basic punctuation like dollar signs, commas, and percent signs can be included.
source: string (optional): The name of your API integration. This will be used inside Koan to show where your goal's metric values came from. If no source is provided, the name API will be used.