Docs
Go to Conductrics.com →
  1. Administrative APIs

Goal Management API

You can use this Administrative API if you have a need to manage Goal Types programmatically (rather than creating and updating them in the Conductrics Admin).

📘

API keys and such

To keep this page relatively clear, we're omitting certain details from the example snippets:

  • These examples assume that your account is available at https://api-v3.conductrics.com. Your account may use a different endpoint (URL), especially if you're using a private Conductrics server or if your Conductrics account is located outside of the United States.
  • These examples show a pretend account code (acc-xxxxxx). You will need to replace that with your actual account code.
  • You also need to provide the admin API key for your account, either as a query parameter called apikey (so, ?apikey=admin-xxxxxxxx) or as a HTTP header called x-conductrics-apikey.

All of the above details are available in the Conductrics Admin, under Developers > API Info & Keys. If you get an "Unauthorized" message when trying to use these APIs, it's likely that one of these items wasn't provided correctly.

Getting a List of Goal Types

To get a list of existing goal types, issue a GET to:

https://api-v3.conductrics.com/admin/acc-xxxxxx/goals

Conductrics will respond with a structure such as the following:

{
	"status": 200,
	"data": [{
		"code": "g-Nd40yzQjDf",
		"name": "Video Play Start",
		"agents": ["a-3eHahm75Oi", "a-H509Pq90EL"]
	}, {
		"code": "g-h5AvSpdBS2",
		"name": "Checkout Complete",
		"agents": ["a-H509Pq90EL"]
	}]
}

You get back an array of summary objects, each one containing:

  • code - the API code for the goal type.
  • name - the friendly name for the goal type (for display in reports, etc).
  • agents - an array of agent codes that the goal type is associated with.

Creating a new Goal Type

This is the same API used behind the scenes when you add a new Goal Type in the Conductrics admin.

To create a goal type, issue a PUT request like this (substituting your new goal type's code):

https://api-v3.conductrics.com/admin/acc-xxxxxx/goals/goal/g-Nd40yzQjDf

The body of the request should be a JSON-formatted object with the following Goal Type at a minimum:

  • code - the API code for the Goal Type. It must match the code in the endpoint URL (shown above). You can make up any goal code you want, as long as it contains only numbers, letters, slashes, and underscores (up to 100 characters). The Conductrics Admin generates codes that start with g- but that is not a requirement for your own goal types.
  • name - the friendly name for the Goal Type (for display in reports, etc), up to 50 characters.
  • agents - an array of agent codes that the Goal Type should be considered associated with. The array may be empty if you only want to register the Goal Type but not associate it with any agents at the moment.

Optional fields that may be provided:

  • countMax - Optional. The number of times a goal of this type will be recorded for a given visitor, for a given agent. The default is 1, meaning that only the first goal event (of this type) triggered for a given visitor will be recorded for each agent. Must be a positive integer.
  • valueMin and valueMax - Optional. For Goal Types that have explicit numeric values conceptually (for instance, when a visitor makes a purchase on an e-commerce site), the minimum and maximum value that should be accepted. Both valueMin and valueMax must be provided to enable numeric rewards from actual visitors at runtime (you will get an error message if you provide one without the other), and the max must be greater than the min. You can send the actual value when your visitors "convert" via the v parameter when sending goal events at runtime.

Updating an Existing Goal Type

The process for updating an existing goal type is the same as creating a new one.

You may provide a partial document if you only want to update some of the fields. For instance you can update just the name by sending {"name": "My New Name"} as the body of the PUT request.

🚧

Keep in mind that if you provide the agents array when updating a goal type (say, to associate a new agent), the list of agent codes in the array you provide replaces the list of current agents. So, you will usually want to GET the Goal Type first to get the currently-associated agents, make your changes to the array, then PUT the changes back.

Retrieving an Existing Goal Type Object

Issue a GET request to the same URL that you'd use to update the object, for example:

https://api-v3.conductrics.com/admin/acc-xxxxxx/goals/goal/g-Nd40yzQjDf

The item returned will contain Goal Type fields as discussed above.

🚧

The returned goal-type object may include some additional fields that are not supported or documented for developer use at this time (they are used internally for Conductrics Express):

  • diagram - used internally for Conductrics Express
  • tags - also used internally for Conductrics Express

Contact Conductrics if you have interest in these items in particular.

Deleting a Goal Type

Issue a DELETE request to the same URL that you'd use to update the object, for example:

https://api-v3.conductrics.com/admin/acc-xxxxxx/goals/goal/g-Nd40yzQjDf

Updated about 1 year ago