About the Contacts API

The Contacts API allows you to manage contact information for your site's customer database. Create, update, and organize contact records with intelligent duplicate detection, member integration, and comprehensive contact data management. Use this API to build CRM systems, manage customer relationships, and synchronize contact data across multiple platforms.

With the Contacts API, you can:

• Manage Contact Information: Create and manage contact records with names, emails, phones, and addresses.
• Handle Contact Deduplication: Automatically detect and prevent duplicate contacts using intelligent matching logic.
• Integrate with Site Members: Integrate with site member accounts for unified user management.
• Manage Contact Organization: Organize contacts using tags and custom extended fields.
• Process Bulk Operations: Perform bulk operations for efficient data processing and imports.
• Manage Marketing Subscription Status: Track and manage contacts subscription preferences to marketing campaigns.
• Handle Image Uploads: Handle contact images with asynchronous upload processing.
• Restore Deleted Contacts: Restore deleted contacts from a 90-day trash bin recovery system.

Important information: The Contacts API uses matching logic to prevent duplicates based on the externalId, email, and phone identifiers. Site member contacts have special restrictions for certain operations. All contact deletions are soft deletes with a 90-day recovery period.

Before you begin

It's important to note the following points before starting to code:

• Required Fields: At least one of name (first/last), email, or phone is required when creating contacts.
• External IDs: externalId can be set only once during creation and can't be changed afterward.
• Site Member Emails: The main email of a contact that is a site member can't be changed through the Contacts API. Update it through the Members API instead.
• Contact Matching: The API uses matching logic based on the externalId, email, and phone identifiers to prevent duplicates. Understanding the matching rules is important for proper contact management.
• Rate Limits: Wix API rate limits allow an app to perform up to 200 requests per minute, per instance. If this limit is exceeded, the app may be throttled.
• Bulk Limits: Synchronous bulk operations are limited to 100 items per request and up to 50 requests per minute. Asynchronous bulk operations by filter are limited to 10 requests per minute. Ensure your app handles these limits gracefully.
• Asynchronous Operations: The by-filter bulk endpoints (such as Bulk Delete Contacts By Filter, Bulk Update Contact Tags By Filter, Bulk Update Phone Country Code By Filter, and Bulk Update Contact Subscriptions) run asynchronously and return a jobId. Pass this ID to Get Async Job to track the operation's progress and results.
• Image Processing: Contact images are processed asynchronously. Use the image upload status endpoints to track processing progress.
• Soft Deletes: Deleted contacts are moved to a trash bin and can be restored within 90 days.
• Member Operations: Operations on member contacts require the Members Area to be installed, and managing members is done through the Members API.
• Eventually Consistent Fields: The memberInfo, email.subscriptionStatus, and phone.subscriptionStatus fields are read-only and materialized from other systems. Changes to the underlying member or marketing consent are reflected after the relevant events are processed, so these values can briefly lag.

Use cases

• Import contacts from external systems
• Manage site member contact integration
• Process bulk contact operations
• Organize contacts with tags and custom data
• Handle contact matching and deduplication

Terminology

• Contact: A person in a site's contact list, storing profile information such as name, email addresses, phone numbers, and addresses. A contact can optionally be linked to a site member.
• Contact matching: The logic that identifies potential duplicate contacts using the externalId, email, and phone identifiers, with priority-based ranking.
• External ID: A unique identifier from an external system, used for contact matching and import synchronization. It can be set only once and can't be changed.
• Site member contact: A contact that is also a registered site member with login credentials. Site member contacts have restrictions on updates and deletion.
• Upsert: An operation that creates a contact when no match is found, or updates an existing contact when a match is found based on the matching logic.
• Subscription status: A contact's opt-in or opt-out preference for email and SMS marketing communications.
• Member info: Additional information available when a contact is also a site member, including member status, login activity, and group memberships.
• Tags: Private labels assigned to contacts for organization and filtering. Tags are visible only to site collaborators.
• Segments: Groups of contacts based on specific criteria, managed through the site dashboard.
• Extended fields: Custom fields for storing business-specific contact data beyond the standard fields. Defined and validated using the Data Extension Schema API.
• Trash bin: Temporary storage for deleted contacts that allows restoration within 90 days before permanent deletion.