Quickstart - API Reference

This guide takes you from zero to a working API call. By the end you'll have a key, you'll have listed the contacts in your workspace, and you'll have added a new one.

The API lives at https://api.audienceful.com/v2/. Every request is authenticated with a workspace API key sent in the X-Api-Key header.

Get an API key

Log in and head to the API keys page under Settings. Click Generate Key, give it a name, and (optionally) set an expiration and scopes. Leave scopes empty for full workspace access while you're getting started.

Copy the key somewhere safe. This is the only time the full key is shown. Store it in an environment variable rather than pasting it into code.

Bash

export AUDIENCEFUL_API_KEY="<your-api-key>"

Your API key is a workspace secret. Never expose it to a browser or mobile client. Call the API from a backend service only.

Make your first request

List the first page of contacts in your workspace. A 200 response means your key works.

curl --location --request GET 'https://api.audienceful.com/v2/people' \
--header "X-Api-Key: $AUDIENCEFUL_API_KEY"

import os
import requests

url = "https://api.audienceful.com/v2/people"
headers = {"X-Api-Key": os.environ["AUDIENCEFUL_API_KEY"]}

response = requests.get(url, headers=headers)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.audienceful.com/v2/people", {
  method: "GET",
  headers: { "X-Api-Key": process.env.AUDIENCEFUL_API_KEY },
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);

You'll get back the standard paginated envelope:

JSON

{
  "data": [
    {
      "id": "jQKdwqp3YRRtTrwqUJEp7d",
      "email": "person@example.com",
      "tags": ["vip"],
      "status": "active"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Add a contact

Now create a contact by sending a POST to the same endpoint. Include an Idempotency-Key so a retry after a network blip never creates a duplicate.

curl --location --request POST 'https://api.audienceful.com/v2/people' \
--header "X-Api-Key: $AUDIENCEFUL_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8' \
--data-raw '{ "email": "new.person@example.com", "tags": ["from-api"] }'

import os
import requests

url = "https://api.audienceful.com/v2/people"
headers = {
    "X-Api-Key": os.environ["AUDIENCEFUL_API_KEY"],
    "Content-Type": "application/json",
    "Idempotency-Key": "8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8",
}
payload = {"email": "new.person@example.com", "tags": ["from-api"]}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.audienceful.com/v2/people", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.AUDIENCEFUL_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8",
  },
  body: JSON.stringify({
    email: "new.person@example.com",
    tags: ["from-api"],
  }),
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

That's it, you're integrated. 🎉

Where to next

Authentication & scopes

Lock keys down to only the permissions an integration needs.

Handle errors

The single error envelope every endpoint returns, and how to react to it.

Stay under rate limits

Per-workspace limits, the headers to watch, and how to back off.

Get webhooks

Be notified when things change instead of polling for updates.