About the Amperity API

The Amperity API enables programmatic access to your Amperity tenant by using a collection of RESTful endpoints that support API-first use cases for integrations, applications, and custom workflows. Use Amperity API endpoints to streamline workflows, enhance marketing strategies, and unlock the value of your brand’s customer data.

Available Endpoints

GET /audit-events GET /campaign-drafts GET /campaigns GET /ingest/jobs GET /ingest/jobs/{id} GET /segments GET /workflow/runs/ GET /workflow/runs/{id} POST /workflow/runs/{id}/stop

OpenAPI specification

Amperity provides an OpenAPI specification for the Amperity API. Download the OpenAPI specification, and then import it into an API tool, such as Postman, to start interacting with Amperity API endpoints.

Versioning

Amperity APIs evolve and change over time. Amperity versions API endpoints to help your brand track changes to the Amperity API and to offer support to developers as these endpoints evolve.

Your team of developers can track improvements to the Amperity API from the changelog. Monitor the changelog to know when new versions are available and/or when existing versions are updated or planned for deprecation.

Authentication

All requests that are made to Amperity API endpoints must be authenticated by access tokens that are signed by Amperity-managed API keys.

Amperity API keys are synthetic identities that are bound to your tenant and enable programmatic access to Amperity.

Access tokens are signed by Amperity-managed API keys and are authorized to perform certain actions with Amperity.

Base URL

All requests made to Amperity API endpoints should be directed to the following base URL:

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

Requests

All requests made to an Amperity API endpoint require a base URL, a tenant ID, and an access token for a valid API key.

In addition to all required headers, you must specify the HTTP method, base URL, and content type. For example:

curl -request GET \
     -url "https://{tenant-id}.amperity.com/api/{endpoint}/" \
     -H "Authorization: Bearer ${access-token}" \
     -H "Amperity-Tenant: {tenant-id}" \
     -H "Content-Type: application/json" \
     -H "api-version: {version}"

Most endpoints have additional endpoint-specific parameters that may be included in the request.

Responses

The Amperity API responds in JSON format. Each response includes relevant HTTP status codes that indicate the success or the failure of a request. The individual properties in a response will vary by endpoint; all endpoints that support the GET HTTP method will return lists using pagination.

Pagination

Amperity uses cursor-based pagination to return pages of data for large lists.

Rate Limits

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.