Getting Started

The fastest way to get comfortable with the Campaign Refinery API is to make one tiny authenticated request first. Once that works, every other protected endpoint uses the same authorization header.

1. Create an API key

Open API settings in Campaign Refinery and create an API key for the account you want to work with.

Keep the key private. Do not put it in browser code, public repos, support tickets, or query strings.

2. Send it as a bearer token

Use the key in the HTTP Authorization header:

Authorization: Bearer YOUR_API_KEY

The new API host is:

https://api.campaignrefinery.com

3. Test authentication

Call the auth test endpoint before building anything larger:

curl -sS "https://api.campaignrefinery.com/api/test/auth" \
  -H "Authorization: Bearer YOUR_API_KEY"

A good key returns:

{
  "status": true,
  "message": "OK"
}

If you get 401, check that the header name is exactly Authorization, the value starts with Bearer , and the key belongs to the Campaign Refinery account you meant to use.

Examples

JavaScript

const apiKey = process.env.CAMPAIGN_REFINERY_API_KEY;

const response = await fetch("https://api.campaignrefinery.com/api/test/auth", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

if (!response.ok) {
  throw new Error(`Campaign Refinery auth failed: ${response.status}`);
}

console.log(await response.json());

Python

import os
import requests

api_key = os.environ["CAMPAIGN_REFINERY_API_KEY"]

response = requests.get(
    "https://api.campaignrefinery.com/api/test/auth",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

PHP

<?php

$apiKey = getenv('CAMPAIGN_REFINERY_API_KEY');

$curl = curl_init('https://api.campaignrefinery.com/api/test/auth');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($status !== 200) {
    throw new RuntimeException('Campaign Refinery auth failed: ' . $status);
}

echo $body;

What to try next

Start with the workflow you are trying to build, not the longest endpoint list.

• Need to add people to Campaign Refinery? Start with Subscribe Contact, then Get Contacts.
• Need to organize contacts? Look at Tags, Forms, and Goals.
• Need engagement or reward data? The Gamification endpoints return points and ranking data by contact UUID.
• Need to send mail directly? Use Send Single Email once your sending domain and footer are configured.
• Migrating from the old REST API? Keep the REST API Migration Guide open while you update paths and authentication.

Most endpoints return a JSON envelope with success, message, and data. The auth test endpoint is deliberately smaller because its only job is to answer: did this key work?