Create a Contact

Creates a new contact in your audience.

POSThttps://api.audienceful.com/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": "person@example.com",
    "tags": ["vip", "newsletter"],
    "publications": ["The Weekly"],
    "extra_data": { "plan": "pro" }
}'
{
  "id": "jQKdwqp3YRRtTrwqUJEp7d",
  "email": "person@example.com",
  "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.

Because of that merge, this is also the endpoint for updating a contact — one upsert you can call repeatedly without first checking whether the contact exists.

Body

emailstringrequired
The contact's email address. Required unless you're addressing an existing contact by id.
idstring
The opaque id of an existing contact to update. Takes precedence over email when both are supplied, which is how you change a contact's email address. An id that doesn't match a contact returns a 404 — unlike email, it never creates one. See Update a Contact.
tagsarray[string]
A list of tag names to apply to the contact. Tags that don't exist yet are created. Tags are always additive — a tag you leave out of a later write is left in place. Example: ["vip", "newsletter"]
publicationsarray[string]
A list of publications (consent streams) to subscribe the contact to. Each entry is a publication's id or its name. Unlike tags, unknown values are rejected with a 400 rather than created on the fly. This only ever grants consent — a publication you leave out is never unsubscribed, so it is safe to send on a merge. To withdraw consent, use Update a Contact's Publications. Example: ["The Weekly"]
notesstring
Notes associated with this contact. HTML string or plain string.
extra_dataobject
Custom field values, keyed by each field's data_name. Custom fields may also be sent as top-level keys (see below).
Properties
custom_fieldstring | boolean | number
An example of a custom field you may have for your audience. The data_name for each field is used as the key. See Fields.
double_opt_instringdefault: not_required
Double opt-in status. Sends a confirmation email if set to required.
Options
not_required
(Default) Double opt-in is not required for this contact.
required
Triggers a double opt-in email and awaits the contact's confirmation.
complete
The contact has already opted in to receive emails.
trigger_automationsbooleandefault: 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.

idstring
The contact's opaque, unique identifier. Send it as id in the body of the update, delete, opt-in, unsubscribe and publications endpoints to address this contact, or use it in the path of the resource-shaped routes. The sequential integer primary key is never exposed.
emailstring
The contact's email address.
tagsarray[string]
The names of the tags applied to this contact — a flat list of strings.
notesstring
Notes associated with this contact. HTML string or plain string.
extra_dataobject
All custom field values for the contact, keyed by each field's data_name (never the internal field id).
Properties
custom_fieldstring | boolean | number
An example of a custom field you may have for your audience. The data_name for each field is listed here. See Fields.
created_atstring
The datetime (UTC) at which the contact was created.
updated_atstring
The datetime (UTC) at which the contact was last updated.
last_activitystring 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.
countrystring or null
The contact's two-letter country code, if known.
statusstring
The single subscription/deliverability indicator for the contact.
Values
active
The contact is active and subscribed.
unconfirmed
The contact has not confirmed their double opt-in email.
bounced
The contact's email failed to deliver (permanent).
unsubscribed
The contact has unsubscribed.
not_subscribed
The contact is not subscribed to marketing.
cleaned
The contact was cleaned from the list (repeatedly undeliverable).
sourcestring
How the contact entered your audience (e.g. api, import, form).
open_ratenumber
The contact's historical email open rate, from 0 to 1.
click_ratenumber
The contact's historical email click rate, from 0 to 1.
Last updated: July 31, 2026
Previous
Retrieve a Contact
Next
Update a Contact