Documentation version: 2026-09-18.3
Canonical: https://docs.creator.gg/guides/contacts.md

# Contacts, audiences, and complete pagination

## Search and read
contacts_search uses page (1-based) and pageLimit (maximum 100). Continue until totals are covered or a short/empty page establishes the end. Do not treat page one as the database. Records can change during pagination; deduplicate returned IDs.

Use contacts_get for current fields/preferences. Search before upsert. IDs identify records; names or shared email addresses may not identify one person.

Tag-filtered search currently returns an account-screen handoff. Supplying tags does not yield a supported filtered API list. Inspect result codes.

## Updates
contacts_upsert follows account deduplication and requires email or phone. contacts_update changes supplied fields only. Dedicated contacts_tags_add/remove changes membership without replacing unrelated tags.

contacts_fields_list supplies live configured IDs, types and fieldKey values; it does not create fields. Use email_merge_fields_list for exact email tokens and category coverage. Preserve unrelated fields/preferences. contacts_suppress_email suppresses email and never clears opt-out. Deletion is destructive, requires deletion intent, and is not an audience-cleaning shortcut.

## Named audiences
audiences_list returns tags used as named audiences. Creating/renaming/deleting audiences changes tags. Contact tag tools add/remove members. Deleting an audience retains contacts.

Email recipients.tagIds uses audience IDs; contact tag tools use tag names. Resolve from actual returned records.

Smart List CRUD, bulk CSV, and duplicate merging require account screens. audiences_smart_lists and contacts_import_export only provide those handoffs.

## Eligibility
Inspect usable email and global/email DND. Exclude missing addresses and active/permanent suppression. Missing preference data is an uncertainty to resolve, not permission to clear preferences.

Report total records, eligible unique recipients, and exclusions. Explicit IDs are checked before sending; tag/segment delivery applies account suppression. Selected audience size is not delivered count.

Resolve ambiguous selection before sending. Do not broaden a segment, truncate at the 100-ID send limit, or send overlapping batches.

## Pagination conventions
Contacts: page/pageLimit, maximum 100.
Email templates/campaigns: offset/limit, maximum 20.
Social posts/media: offset/limit, maximum 100.
Template folders need traversal and are not templates.

Operation-specific data envelopes can contain contacts, items, campaigns, or results. Use actual entries/totals. Empty, missing, and failed results differ.