Skip to main content
POST
/
v2
/
people
curl --location --request POST 'https://api.audienceful.com/v2/people' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data-raw '{
    "email": "[email protected]",
    "tags": ["vip", "newsletter"],
    "extra_data": { "plan": "pro" }
}'

import requests

url = "https://api.audienceful.com/v2/people"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
}
payload = {
    "email": "[email protected]",
    "tags": ["vip", "newsletter"],
    "extra_data": {
        "plan": "pro",
    },
}

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

const response = await fetch("https://api.audienceful.com/v2/people", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
  },
  body: JSON.stringify({
    "email": "[email protected]",
    "tags": [
      "vip",
      "newsletter"
    ],
    "extra_data": {
      "plan": "pro"
    }
  }),
});
const data = await response.json();
console.log(data);

{
  "id": "jQKdwqp3YRRtTrwqUJEp7d",
  "email": "[email protected]",
  "tags": ["vip"],
  "notes": "",
  "extra_data": {
    "plan": "pro"
  },
  "created_at": "2026-07-04T12:00:00Z",
  "updated_at": "2026-07-04T12:00:00Z",
  "last_activity": "2026-07-04T12:00:00Z",
  "country": "US",
  "status": "active",
  "source": "api",
  "open_rate": 0.42,
  "click_rate": 0.11
}
Requires the people:write scope.
Contacts are keyed by email. If a contact with the given email already exists, this endpoint merges the supplied data into that contact and returns 200 instead of creating a duplicate. New contacts return 201.

​
Body

​
email
string
required
The contact’s email address.
​
tags
array[string]
A list of tag names to apply to the contact. Tags that don’t exist yet are created. On a merge, these are added to the contact’s existing tags. Example: ["vip", "newsletter"]
​
notes
string
Notes associated with this contact. HTML string or plain string.
​
extra_data
object
Custom field values, keyed by each field’s data_name. Custom fields may also be sent as top-level keys (see below).
​
double_opt_in
string
default:"not_required"
Double opt-in status. Sends a confirmation email if set to required.
​
trigger_automations
boolean
default:"false"
Enroll the contact in any matching automations when they’re added.
​
<custom_field_data_name>
string | boolean | number
Custom field values may also be sent as top-level keys named by the field’s data_name, instead of nesting them under extra_data.

​
Response

Returns 201 Created with the new contact, or 200 OK with the merged contact if one with that email already existed.
​
id
string
The contact's opaque, unique identifier. Use this value to address the contact in the URL of the retrieve, update, and delete endpoints. The sequential integer primary key is never exposed.
​
email
string
The contact's email address.
​
tags
array[string]
The names of the tags applied to this contact — a flat list of strings.
​
notes
string
Notes associated with this contact. HTML string or plain string.
​
extra_data
object
All custom field values for the contact, keyed by each field's data_name (never the internal field id).
​
created_at
string
The datetime (UTC) at which the contact was created.
​
updated_at
string
The datetime (UTC) at which the contact was last updated.
​
last_activity
string or null
The datetime (UTC) of this contact's last activity. Example activities that update this field are: creation, opening an email, clicking an email, and unsubscribing.
​
country
string or null
The contact's two-letter country code, if known.
​
status
string
The single subscription/deliverability indicator for the contact.
​
source
string
How the contact entered your audience (e.g. api, import, form).
​
open_rate
number
The contact's historical email open rate, from 0 to 1.
​
click_rate
number
The contact's historical email click rate, from 0 to 1.
curl --location --request POST 'https://api.audienceful.com/v2/people' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data-raw '{
    "email": "[email protected]",
    "tags": ["vip", "newsletter"],
    "extra_data": { "plan": "pro" }
}'

import requests

url = "https://api.audienceful.com/v2/people"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
}
payload = {
    "email": "[email protected]",
    "tags": ["vip", "newsletter"],
    "extra_data": {
        "plan": "pro",
    },
}

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

const response = await fetch("https://api.audienceful.com/v2/people", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
  },
  body: JSON.stringify({
    "email": "[email protected]",
    "tags": [
      "vip",
      "newsletter"
    ],
    "extra_data": {
      "plan": "pro"
    }
  }),
});
const data = await response.json();
console.log(data);

{
  "id": "jQKdwqp3YRRtTrwqUJEp7d",
  "email": "[email protected]",
  "tags": ["vip"],
  "notes": "",
  "extra_data": {
    "plan": "pro"
  },
  "created_at": "2026-07-04T12:00:00Z",
  "updated_at": "2026-07-04T12:00:00Z",
  "last_activity": "2026-07-04T12:00:00Z",
  "country": "US",
  "status": "active",
  "source": "api",
  "open_rate": 0.42,
  "click_rate": 0.11
}