Contacts, custom fields & lists

Everything in WeZend hangs off the contact — one profile per human, holding identifiers (email, phone), attributes, consent state, event history, messages and scores.

Standard + custom fields

Contacts ship with the standard fields you'd expect (name, email, phone, country, language…). Everything else is a custom field you define once:

curl -X POST https://api.wezend.com/v1/contacts/fields \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Loyalty tier" }'

The /v1/contacts API accepts either an API key (X-API-Key) or a dashboard session (a JWT from POST /v1/auth/login) — a server-side integration uses the key. Anything that creates or modifies data needs a key with the write scope; a read-scoped key is rejected with 403 insufficient_scope. The field key (loyalty_tier) is derived automatically from the label. Once defined, the field is available everywhere — in template variables ({{loyalty_tier}}), in the segment builder, on the contact card in the dashboard, and in CSV imports.

Creating & updating

# Create
curl -X POST https://api.wezend.com/v1/contacts \
  -H "X-API-Key: $WEZEND_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": "anna@example.com", "phone": "+4512345678", "first_name": "Anna", "custom_fields": { "loyalty_tier": "gold" } }'

# Update (partial — only the fields you send change)
curl -X PATCH https://api.wezend.com/v1/contacts/c_123 \
  -H "X-API-Key: $WEZEND_API_KEY" -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "loyalty_tier": "platinum" } }'

Contacts are matched on email/phone, so importing the same person twice updates rather than duplicates.

CSV import

Audience → Contacts → Import (or POST /v1/contacts/import). Upload the file, map your columns to fields (unmapped columns can become new custom fields on the spot), choose the target list, and confirm. Imports run in the background with a progress indicator and a per-row error report — a bad phone number on row 3,481 doesn't kill the other 50,000 rows.

Lists vs. segments — when to use which

• A list is static: contacts are in it because you put them there (import, form signup, manual add). Membership only changes when something adds/removes them.
• A segment is live: a rule ("spent > €500 AND inactive 30 days") that contacts flow in and out of automatically as their data changes.

Rule of thumb: lists for provenance ("Spring fair leads 2026"), segments for state ("currently at churn risk"). Campaigns and journeys accept both.

The lists API

Lists take the same two credentials as contacts — an API key (X-API-Key) or a dashboard JWT. Everything below except the reads is a write, so a read-scoped key gets 403 insufficient_scope.

# Create a list
curl -X POST https://api.wezend.com/v1/lists \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring fair leads 2026", "description": "Booth scans" }'

# Add a contact that already exists
curl -X POST https://api.wezend.com/v1/lists/$LIST_ID/contacts \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "c_123" }'

# Import a CSV straight into the list (multipart, max 50 MB)
curl -X POST https://api.wezend.com/v1/lists/$LIST_ID/import \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -F "file=@leads.csv"

GET /v1/lists and GET /v1/lists/:id read them, PATCH /v1/lists/:id renames one, PATCH /v1/lists/:id/favorite pins it in the dashboard, and DELETE /v1/lists/:id plus DELETE /v1/lists/:id/contacts/:contactId remove a list or a single membership. Adding a contact twice is a no-op rather than an error, so an import you re-run won't duplicate anyone.