Skip to main content
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.

​
1. Get an API key

1

Open your API settings

Log in and head to the API keys page under Settings.
2

Generate a key

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.
3

Copy it somewhere safe

This is the only time the full key is shown. Store it in an environment variable rather than pasting it into code.
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.

​
2. 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: 
{
  "data": [
    {
      "id": "jQKdwqp3YRRtTrwqUJEp7d",
      "email": "[email protected]",
      "tags": ["vip"],
      "status": "active"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

​
3. 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": "[email protected]", "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": "[email protected]", "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: "[email protected]",
    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.
Prefer to explore interactively? Every endpoint in the API Reference has a live playground — drop in your key and send real requests from the browser.