Introduction
Manage your audience programmatically — contacts, custom fields, automations, transactional email, send reports, and webhooks.
Welcome to the Audienceful developer docs. The API v2 lets you do everything the app does — sync contacts, manage custom fields, trigger automations, send transactional emails, pull send reports, and subscribe to webhooks — straight from your own backend.
It's a resource-oriented JSON API with predictable URLs, cursor pagination, a consistent error envelope, and idempotent writes. If you've used a modern REST API before, this will feel familiar.
Base URL
The Audienceful API is located at:
https://api.audienceful.com/v2/
v2 is the current API and all new integrations should use it. Every request is authenticated with an API key in the X-Api-Key header.
Addressing a contact
Every single-contact endpoint takes the identifier in the request body, as either id (the contact's opaque id) or email:
curl --location --request POST 'https://api.audienceful.com/v2/people/delete' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data-raw '{ "email": "alex+news@example.com" }'
| Operation | Endpoint |
|---|---|
| Create or update | POST /v2/people |
| Delete | POST /v2/people/delete |
| Confirm double opt-in | POST /v2/people/opt-in |
| Unsubscribe | POST /v2/people/unsubscribe |
| Read or set consent | POST /v2/people/publications |
To retrieve a contact, use GET /v2/people/{id} when you hold their id, or filter the list — GET /v2/people?email=... — when you hold their address. A query string is escaped for you; a path segment is not.
Email addresses do not belong in a URL path. They end up in access logs, proxy caches and browser history, and the characters that are legal in an address but structural in a URL — /, ?, #, % — have to be percent-encoded, which client libraries do for you everywhere except the path. A half-escaped address is a 404 that looks like a missing contact.
The resource-shaped path forms (GET /v2/people/{id}, PATCH /v2/people/{id}, DELETE /v2/people/{id}, and the {id} sub-routes) still work and are not deprecated — they're a good fit when you hold an id and want a cacheable URL. Each endpoint's page documents both.
Core concepts
Before you write your first request, it's worth skimming the shared conventions that apply across every endpoint.
Resources
Build your own solution for growing and managing your audience. We're continually adding functionality to the public API as we ship improvements and new features.
Can't find an endpoint for what you need? Let us know and we'll make it available as soon as possible.
OpenAPI & SDKs
A machine-readable OpenAPI 3 schema covering the public v2 endpoints is served at https://api.audienceful.com/v2/openapi.json. Use it to generate a typed SDK in your language of choice, import the API into Postman or Insomnia, or keep your own reference in sync.