Getting Started

The CSP API offers both pull and push models of communication between the CSP and TCR. Depending on your requirements, you can choose to implement one or both. The pull model utilizes API calls for querying or updating TCR entities, while the push model uses webhooks to send notifications of events or updates.

For example, a CSP could pull campaign details by calling the GET /campaign/{campaignID} endpoint and have notifications pushed to them via a webhook whenever a new campaign or brand is registered in TCR (see Webhooks and Event Notifications for more information).

Developers can use cURL commands to perform actions, transfer data, and interact with the CSP API. All examples in this developer portal are shown using cURL commands. There are, however, a few more steps that need to take place before you can begin submitting requests.

You must be registered as a CSP with TCR. Visit The Campaign Registry website to sign up.
You need to have a set of API keys to interact with the CSP API (see API Keys).
It’s a good idea to review the Basic Concepts to understand how the TCR platform works.

Authentication

REST operations in the CSP API are only accessible via HTTPS to ensure that any data transferred between TCR and your application is encrypted. To protect against unauthorized access, TCR requires call-level authentication of your identity using Basic Authentication.

Accounts with the Manager or User role are responsible for generating API KEY and SECRET authentication tokens (see API Keys). These tokens are passed as Username and Password values in the basic authentication header for the appropriate environment.

The following example shows placeholders in a call to retrieve all the available entity types on the TCR platform where SERVER identifies the environment:

CODE

$ curl --user [APIKEY]:[SECRET] GET "http://[SERVER]/v2/enum/entityType" -H "accept: application/json"

Environments

TCR uses several environments for development, testing, and deployment of the code that makes up its products. In addition to a live production environment, there are additional environments for internal testing and for testing by customers.

Environment

Description

QA

An internal testing environment where new features are deployed a week prior to release. QA is a dynamic environment that is not as reliable as Staging since it’s used for internal testing. Integrations using the QA environment will not impact customer operations.

Access can be requested by customers in order to test new features, but it’s important to note that it contains code that is actively being tested. Some features may not work as expected.

Staging

An environment where ready-to-release features are deployed a day before product release. This is a stable environment that customers can use to test new features and their own integrations. Integrations using the Staging environment will not impact customer operations.

CSPs should test their code in the Staging environment before deployment to Production.

Production

This is the live production environment for TCR’s products and customers. Integrations using the Production environment will impact live data and customer operations.

API Keys

To get API keys, you’ll need someone with a Manager or User role to log in to the CSP portal for the environment where you’ll be making calls.

API Keys used in one environment will not work in another (i.e., keys used in the QA environment will not work in the Staging environment).

Once logged in to the proper portal, click on Integrations in the sidebar.
In the API Keys section, click Add New.
A new row will appear that contains the API Keys as well as actions for managing them.
Click Copy below API Key to copy the token for the Username value.
Click Copy below Secret to copy the token for the Password value.

API Rate Limiting

The CSP API utilizes rate limits to restrict the number of API calls a CSP account can make within a given time period. If this limit is exceeded, CSP API requests will fail with an HTTP status code of 429. Unless specified otherwise, all GET operations are rate-limited at 20 requests per second, while all PUT, POST, and DELETE operations are rate-limited at 20 requests per 10 seconds.

The pull model utilizes API calls for querying or updating TCR entities, while the push model uses webhooks to send notifications of events or updates. For example, a CSP could pull campaign details by calling the GET /campaign/{campaignID} endpoint and have notifications pushed to them via a webhook whenever a new campaign or brand is registered in TCR.

Additional Resources

OpenAPI Specification: An interactive OpenAPI specification document for the Staging environment can be found at: https://csp-api-staging.campaignregistry.com/v2/restAPI.
API Version and Changelogs: The CSP API version number can be retrieved via the GET /version endpoint. For information on updates and changes, view the changelog. For questions, contact TCR Support.