In order to use the Quantive API you will need your Account ID and API Token. If you don't already have those, refer to the API Setup Guide. Once you have copied your Account ID and API Token, you can follow along with these examples and start utilizing all the API Methods.

API Structure

For each of these examples, we will be using the same API URL. The URL you will use depends on the Data Center of your Quantive Account. To know which URL to use, login to Quantive , and if the URL is includes '.us.gtmhub', then you will need to use the US URL.

In addition to the URL, each request will need to be made with a header. This should contain 3 pieces of information: Account ID, API Token, and Content-Type.

Your setup should looks something like this:

url = 'https://app.us.gtmhub.com/api/v1/goals' 
account_id = '' # Replace with your Account ID
api_token = '' # Replace with your API Token

headers = {
	'Authorization': 'Bearer %s' % api_token, 
	'gtmhub-accountId': account_id, 
	'Content-Type': 'application/json' 
}

Note: Remember you include 'Bearer ' in your Authentication header!

Creating an Objective

To get started with the API, let's first create an Objective. To do this, we will first need to create a dictionary that represents the Objective, which will include Name, Session ID, and Owner ID. Then, we can POST that Objective to the /goals API.

import requests, json

## Using the url/headers definitions from above

# Create the Objective Object
objective = {
	'name': 'New Objective',
	'sessionId': '', # Replace with your Session ID
	'ownerId': '', # Replace with your Owner ID
	'tags': [{'title': 'Test Tag'}]
} 

# POST the Objective to the /goals API
response = requests.post(url, data=json.dumps(objective), headers=headers) 

# Save the newly created Objective ID
objective_id = response.json()['id']

Note: Session ID and Owner ID can be found either by looking at the URL for each in the Dashboard, or by querying each through the API

Updating an Objective

Now that we have created an objective, we can use the API to update it. Let's add a description to our Objective.

import requests, json

## Using the url/headers/objective_id definitions from above

# Update URL to specify the Objective ID
update_url = '%s/%s' % (url, objective_id)

# Format the information you want to update
objective_update = {
	'description': 'Objective created through the API'
} 

# PATCH the update to the /goals API
response = requests.patch(update_url, data=json.dumps(objective_update), headers=headers)

Reading Objectives

With this information now saved to your account, we can use the API to return objectives in the account. Here, we will query only Objectives that contain the 'Test Tag' we created above.

import requests, json

## Using the url/headers definitions from above

# Update URL to filter on Objective tag
filtered_url = url + '?tags=Test Tag' 

# GET all goals in the account with the 'Test Tag'
response = requests.get(filtered_url, headers=headers) 
filtered_objectives = response.json()['items']

Deleting an Objective

Finally, we can finish these examples removing the Objective we created.

import requests, json

## Using the url/headers/objective_id definitions from above

# Update URL with the objective_id
delete_url = '%s/%s' % (url, objective_id) 

# DELETE the goal
response = requests.delete(delete_url, headers=headers)

Full Example

Here is the full example of all CRUD operations.

import requests, json

url = 'https://app.us.gtmhub.com/api/v1/goals' 
account_id = '' # Replace with your Account ID
api_token = '' # Replace with your API Token
headers = {
	'Authorization': 'Bearer %s' % api_token, 
	'gtmhub-accountId': account_id, 
	'Content-Type': 'application/json' 
}

# Create the Objective Object
# POST the Objective to the /goals API
# Save the newly created Objective ID
objective = {
	'name': 'New Objective',
	'sessionId': '', # Replace with your Session ID
	'ownerId': '', # Replace with your Owner ID
	'tags': [{'title': 'Test Tag'}]
} 
response = requests.post(url, data=json.dumps(objective), headers=headers) 
objective_id = response.json()['id']

# Update URL to specify the Objective ID
# Format the information you want to update
# PATCH the update to the /goals API
update_url = '%s/%s' % (url, objective_id)
objective_update = {
	'description': 'Objective created through the API'
} 
response = requests.patch(update_url, data=json.dumps(objective_update), headers=headers)

# Update URL to filter on Objective tag
# GET all goals in the account with the 'Test Tag'
filtered_url = url + '?tags=Test Tag' 
response = requests.get(filtered_url, headers=headers) 
filtered_objectives = response.json()['items'] 

# Update URL with the objective_id
# DELETE the goal
delete_url = '%s/%s' % (url, objective_id) 
response = requests.delete(delete_url, headers=headers)