Use tags to record where the contact came from — you can segment and trigger automations on tags later.
Idempotent sync: upsert
If the same email may be submitted more than once, use upsert instead — it creates the contact if new, updates it if it exists, and won’t fail on duplicates.
Unsubscribes and resubscribes
A sync never brings back an unsubscribed contact by accident. If an update, upsert or create sends contact_type: "active" for a contact that is unsubscribed, bounced or complained, its status stays as it is, the other fields are saved, and the response says so:
{ "message": "Contact updated", "warnings": [ { "code": "status_not_changed", "current_status": "unsubscribed", "message": "Status was not changed." } ]}
When a reader turns your emails back on (for example on their account page), call Resubscribe Contact with a record of their consent:
200: re-subscribed (changed: false if they already were).
202: your account has double opt-in on for API and integrations; the reader gets a confirmation email and is re-subscribed when they click it.
409: bounced, spam-complaint, abuse and suppressed contacts can’t be re-subscribed.
Only re-subscribe readers who gave you their consent again. The consent fields are stored in the contact’s activity log as your statement.
Bulk: batch create
For imports, send up to a full batch in one call with contacts (array) and list_id. For very large one-time migrations, consider the CSV import wizard in the app instead — it includes field mapping and validation.
Custom fields
Contacts accept a custom_fields object keyed by your account’s custom-field IDs. List your fields via the app under Audience → Custom fields, or see Custom Properties to manage them via API.