GET /campaigns¶

Use the /campaigns endpoint to return a list of campaigns from your tenant. You may restrict the list of campaigns to those associated with a specific data template.

Available HTTP methods¶

Prerequisites¶

Base URL¶

All requests made to the /campaigns endpoint should be directed to the following base URL:

https://{tenant-id}.amperity.com/api/campaigns/

Rate limit¶

A rate limit is the number of requests that may be made to the Amperity API in a given time period.

The Amperity API supports requests to endpoints that do not exceed a rate of 10 requests per second. Response times will vary by endpoint and the complexity of data that is returned by the response. Some requests may take seconds to return.

Requests to the Amperity API that exceed 10 requests per second may return an error response with an HTTP 429 status code.

Requests¶

A request to the /campaigns endpoint is similar to:

curl --request GET \
       'https://tenant.amperity.com/api/campaigns \
       ?limit=12 \
       ?with_total=true \
       ?destination_data_template_id=ptg-1abcAB4C2' \
     --header 'amperity-tenant: tenant' \
     --header 'api-version: 2024-04-01' \
     --header 'Authorization: Bearer token'

(This example is formatted for readability in a narrow page layout.)

Request parameters¶

The following table describes the parameters that may be used with the /campaigns endpoint.

Parameter	Description
api_version	String. Optional. A supported version of the Amperity API. For example: 2024-04-01. Note You may use the api-version request header instead of the api_version request parameter.
destination_data_template_id	String. Optional. Use this parameter to restrict the list of campaigns that are returned to only campaigns that are configured to use a specific data template. Tip You can find the ID for the data template from the Amperity user interface. From the Destinations page, open the menu in the same row as the data template for which the ID is to be copied, and then select Copy ID.
limit	Integer. Optional. The maximum number of records to include in a single page of results.
next_token	String. Optional. An opaque token that is used to paginate results. Omit the next_token property to return the first page. Use the cursor value for next_token that was returned in a response to view the next page of results. For example: ABCd1fghIJk2l3M Note The possible values for next_token are returned within the 200 response. Important The value for next_token cannot be NULL.
with_total	Boolean. Optional. Set this value to true to include a total count of all results. Default value: false. Note Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set.

Request examples¶

The following examples show how to send requests to the /campaigns endpoint.

cURL¶

The following example shows how to use cURL to send a request to the /campaigns endpoint.

curl --request GET \
       'https://tenant.amperity.com/api/campaigns \
       ?limit=12 \
       &with_total=true \
       &destination_data_template_id=ptg-1abcAB4C2' \
     --header 'amperity-tenant: tenant' \
     --header 'api-version: 2024-04-01' \
     --header 'Authorization: Bearer token'

(This example is formatted for readability in a narrow page layout.)

Python¶

The following example shows how to use Python to send a request to the /campaigns endpoint. This example converts the JSON response into a CSV file named “campaigns.csv”.

import requests
import json
import csv

# URL for Campaigns endpoint
url = "https://tenant-name.amperity.com/api/campaigns"

# Required headers
headers = {
  'accept': 'application/json',
  'authorization': 'Bearer token', # add token here
  'amperity-tenant': 'tenant-name',
  'api-version': 'version'
}

# Query parameter for data template IDs
payload = {
  # 'destination_data_template_id': ''
}

# Get the response from the Campaigns endpoint
response = requests.request("GET", url, headers=headers, params=payload)
response_json = response.json()

# Extract headers from the first data entry
headers = list(response_json["data"][0].keys())

# Specify the output CSV file path
csv_file_path = "campaigns.csv"

# Write data to a CSV file
with open(csv_file_path, mode='w', newline='') as file:
  writer = csv.DictWriter(file, fieldnames=headers)
  writer.writeheader()
  for entry in response_json["data"]:
    writer.writerow(entry)

print("CSV file generated successfully.")

Responses¶

A response from the /campaigns endpoint will match an HTTP status code. A 200 response will contain the results set. A 4xx response indicates an issue with the configuration of your request. A 5xx response indicates that the endpoint is unavailable.

200 OK¶

The 200 response returns a set of campaigns.

{
  "total": 0,
  "next_token": "ABCa1bcdDEe2f3G",
  "data": [
    {
      "id": "ab-1CDEfGHI",
      "name": "Holiday Campaign",
      "deliver_at": "2024-04-22T20:30:00Z"
    },
    {
      "id": "cd-2FGHiJKL",
      "name": "Returning Customers",
      "deliver_at": "2024-04-23T21:00:00Z"
    }
  ]
}

Response parameters¶

A 200 OK response contains the following parameters.

Parameter

Description

data

A JSON array of values for the current page of results. The array of values includes the following properties:

deliver_at: The date and time at which the campaign was delivered (or will be delivered). Dates and times are in ISO 8601 format and in UTC.
id: The Amperity internal identifier for the campaign.
name: The name of the campaign.

next_token

The cursor value to use in a subsequent request to return the next page of results.

Note

When the value for next_token is empty, the last page in the results set has been returned.

total

The total count of all results. This property is only returned when with_total is set to true in a request.

Note

Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set.