Contacts: Supported Filters, Sorting, and Search

This article covers field support for filtering, sorting, and searching in the Contacts API, including for extended fields.

The table below shows field support for filters, sorting, and free-text searching for the base set of contact properties. It doesn't include extended fields (those are covered in the sections below).

FieldSupported FiltersSortableSearchable
id$eq, $ne, $in, $exists
createdDate$eq, $ne, $gt, $lt, $gte, $lteSortable
updatedDate$eq, $ne, $gt, $lt, $gte, $lte
lastActivity.activityDate$eq, $ne, $gt, $lt, $gte, $lteSortable
primaryInfo.email$eq, $ne, $in, $exists, $startsWithSortable
primaryInfo.phone$eq, $ne, $in, $exists, $startsWith
info.name.first$eq, $ne, $in, $exists, $startsWithSortableSearchable
info.name.last$eq, $ne, $in, $exists, $startsWithSortableSearchable
info.emails.email$eq, $ne, $in, $exists, $startsWithSearchable
info.phones.phone$eq, $ne, $in, $exists, $startsWithSearchable
info.phones.e164Phone$eq, $ne, $in, $exists, $startsWithSearchable
info.addresses.street$eq, $ne, $in, $exists, $startsWith
info.addresses.city$eq, $ne, $in, $exists, $startsWith
info.addresses.subdivision$eq, $ne, $in, $exists
info.addresses.country$eq, $ne, $in, $exists
info.company$eq, $ne, $in, $exists, $startsWithSortable
info.jobTitle$eq, $ne, $in, $exists, $startsWithSortable
info.birthdate$eq, $ne, $gt, $lt, $gte, $lteSortable
info.locale$eq, $ne, $in, $exists
info.labelKeys$hasSome, $hasAll
info.locations$hasSome, $hasAll

The table below shows field support for filters, sorting, and free-text searching for the Wix-defined extended fields (also known as system fields).

Note: When querying or sorting, extended field names are flattened to a dot-separated string, like this: "info.extendedFields.{key}". For example, to query the emailSubscriptions.effectiveEmail extended field, use this flattened field name: "info.extendedFields.emailSubscriptions.effectiveEmail".

FieldSupported FiltersSortableSearchable
invoices.vatId
members.membershipStatus$eq,$ne,$in, $nin
emailSubscriptions.deliverabilityStatus$eq,$ne,$in, $nin
emailSubscriptions.subscriptionStatus$eq,$ne,$in, $nin
emailSubscriptions.effectiveEmail$existsSortable

Extended fields that are created by 3rd-party apps or site contributors are known as custom fields. Site contributors can add, remove, and change custom field names from the Contact List in their site's Dashboard.

The table below shows field support for filters, sorting, and free-text searching for custom fields.

Note: When querying or sorting, extended field names are flattened to a dot-separated string, like this: "info.extendedFields.{key}". For example, to query the custom.newCustomer extended field, use this flattened field name: "info.extendedFields.custom.newCustomer".

Data Type/FormatSupported FiltersSortable
String$eq, $ne, $in, $startsWithSortable
Number$eq, $ne, $gt, $lt, $gte, $lteSortable
Date string in YYYY-MM-DD format$eq, $ne, $gt, $lt, $gte, $lteSortable

Related content: API Query Language, Query Contacts

Was this helpful?
Yes
No

Last Activity Types

When a contact interacts with a site, the interaction is captured in lastActivity in the contact object. The table below shows the possible activityType values and describes the interactions each activity type represents:

Activity TypeDescription
GENERALVisited the site.
CONTACT_CREATEDBecame a new contact.
MEMBER_LOGINLogged in.
MEMBER_REGISTERRequested site membership.
MEMBER_STATUS_CHANGEDWas approved, blocked, or unblocked.
FORM_SUBMITTEDSubmitted a form.
INBOX_FORM_SUBMITTEDStarted a chat.
INBOX_PAYMENT_REQUEST_PAIDPaid a payment request.
INBOX_MESSAGE_TO_CUSTOMERReceived a message from a site contributor.
INBOX_MESSAGE_FROM_CUSTOMERSent a new message to the site.
NEWSLETTER_SUBSCRIPTION_FORM_SUBMITTEDSubscribed to a site newsletter.
NEWSLETTER_SUBSCRIPTION_UNSUBSCRIBEUnsubscribed from a site newsletter.
ECOM_PURCHASEMade a Wix Stores purchase.
ECOM_CART_ABANDONAbandoned their shopping cart.
ECOM_CHECKOUT_BUYERChecked out shopping cart and submitted buyer info (but didn’t complete purchase yet).
BOOKINGS_APPOINTMENTBooked an appointment.
HOTELS_RESERVATIONMade a Wix Hotels reservation.
HOTELS_PURCHASEPaid for a Wix Hotels reservation.
HOTELS_CONFIRMATIONConfirmed a Wix Hotels reservation.
HOTELS_CANCELCanceled a Wix Hotels reservation.
VIDEO_PURCHASEPurchased a video.
VIDEO_RENTRented a video.
CASHIER_BUTTON_PURCHASEMade a purchase with a pay button.
ARENA_NEW_LEADBecame a new Wix Marketplace lead.
EVENTS_RSVPResponded that they're attending an event.
INVOICE_PAYPaid an invoice.
INVOICE_OVERDUEContact's invoice is now overdue.
PRICE_QUOTE_ACCEPTAccepted a price quote.
PRICE_QUOTE_EXPIREContact’s price quote has expired.
RESTAURANTS_ORDEROrdered food with Wix Restaurants.
RESTAURANTS_RESERVATIONMade a Wix Restaurants reservation.
SHOUTOUT_OPENOpened an email from the site.
SHOUTOUT_CLICKClicked a link in an email from the site.
CONTACT_MERGEDMerged with another contact.
NEWSLETTER_SUBSCRIPTION_SUBSCRIBESubscribed to a site newsletter.
NEWSLETTER_SUBSCRIPTION_PENDINGSubscription status to site newsletters is pending confirmation.
NEWSLETTER_SUBSCRIPTION_NOT_SETSubscription status to site newsletters is not set.
Was this helpful?
Yes
No

Contact Object

Properties
idstringRead-onlyformat GUID

Contact ID.


revisionintegerRead-only

Revision number, which increments by 1 each time the contact is updated. To prevent conflicting changes, the existing revision must be used when updating a contact.


sourceobjectRead-only

Details about the contact's source.


createdDatestringRead-onlyformat date-time

Date and time the contact was created.


updatedDatestringRead-onlyformat date-time

Date and time the contact was last updated.


lastActivityobjectRead-only

Details about the contact's last action in the site.


primaryInfoobjectRead-only

Contact's primary phone and email.


infoobject

Contact's details.

Was this helpful?
Yes
No

GetList Contacts

Retrieves a list of up to 1,000 contacts per request.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/contacts/v4/contacts

Was this helpful?
Yes
No

PostCreate Contact

Creates a new contact.

The request body must include a name, a phone number, or an email address. If all 3 of these parameters are missing, the contact won't be created.

By default, if the creation request contains an email already in use by another contact, the new contact won't be created. To override this behavior, set allowDuplicates to true.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/contacts

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

DeleteDelete Contact

Deletes a contact.

Deleting a contact permanently removes them from the Contact List.

If a contact is also a site member or site contributor, or has a valid billing subscriptions, the contact cannot be deleted. The related site member or site contributor must first be deleted and any valid billing subscriptions must be canceled, before the contact can also be deleted.

Members are typically associated with a contact, each having a distinct member and contact ID. When passing the ID as a parameter, avoid presuming the IDs are identical since they represent separate entities.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Manage Members
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/contacts/v4/contacts/{contactId}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PatchUpdate Contact

Updates a contact.

Each time the contact is updated, revision increments by 1. The existing revision must be included when updating the contact. This ensures you're working with the latest contact information, and it prevents unintended overwrites.

Members are typically associated with a contact, each having a distinct member and contact ID. When passing the ID as a parameter, avoid presuming the IDs are identical since they represent separate entities.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/contacts/v4/contacts/{contactId}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostMerge Contacts

Merges source contacts into a target contact.

Merging contacts has these effects on the target contact:

  • No target contact data is overwritten or deleted.
  • Arrays (emails, phones, addresses, and labels) are merged from the source contacts.
  • If merging more than one source contact, the 1st source is given precedence, then the 2nd, and so on.

Important: Merges cannot be undone. Use Preview Merge Contacts to test before merging.

Source contacts are deleted when merging. However, if a source contact is a site member or contributor, the merge fails because site contributors and members can't be deleted. Site members and contributors can be target contacts only.

After merging, if you call Get Contact with a deleted source contact ID, the target contact ID is returned. This is supported when calling Get Contact only. Deleted source contact IDs are not supported on any other endpoint.

Merging contacts triggers these webhooks:

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/contacts/{targetContactId}/merge

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostPreview Merge Contacts

Previews merging source contacts into a target contact.

This endpoint performs a dry run without deleting or updating any contacts. A preview of the updated target contact is returned, but no data is changed in the Contact List.

To perform the actual merge, use Merge Contacts.

Members are typically associated with a contact, each having a distinct member and contact ID. When passing the ID as a parameter, avoid presuming the IDs are identical since they represent separate entities.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/contacts/{targetContactId}/preview-merge

Was this helpful?
Yes
No

PostLabel Contact

Adds labels to a contact.

Members are typically associated with a contact, each having a distinct member and contact ID. When passing the ID as a parameter, avoid presuming the IDs are identical since they represent separate entities.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/contacts/{contactId}/labels

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

DeleteUnlabel Contact

Removes labels from a contact.

If a label is no longer needed and you want to remove it from all contacts, you can delete it with Delete Label (in the Labels API).

Members are typically associated with a contact, each having a distinct member and contact ID. When passing the ID as a parameter, avoid presuming the IDs are identical since they represent separate entities.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/contacts/v4/contacts/{contactId}/labels

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Contacts

Retrieves a list of contacts, given the provided paging, filtering, and sorting. Up to 1,000 contacts can be returned per request.

For a detailed list of supported operations, see filtering and sorting for contact properties, extended fields, and custom fields. To learn how to query contacts, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/contacts/query

Was this helpful?
Yes
No

GetList Facets

Lists facets from the site’s Contact List. Facets are labels and subscription statuses. Each facet returns its details (such as key and value), as well as aggregated count of the number of contacts the facet applies to.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/contacts/v4/contacts/facets

Was this helpful?
Yes
No

PostQuery Facets

Retrieves facets from the site’s Contact List by filter. Facets are labels and subscription statuses. Each facet returns its details (such as key and value), as well as aggregated count of the number of contacts the facet applies to.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/contacts/facets/query

Was this helpful?
Yes
No

PostBulk Delete Contacts

Deletes multiple contacts.

All contacts that meet the specified filter and search criteria are deleted. The request should contain a filter value or a search value, or both. To perform a dry run, use the intended filter options with Query Contacts.

When this endpoint is used, a bulk job is started and the job ID is returned. The job might not complete right away, depending on its size. The job's status can be retrieved with Get Bulk Job or List Bulk Jobs.

The following errors can happen while processing the bulk and they will appear in the bulk job:

  • CANNOT_DELETE_SITE_MEMBERS - Contact is a site member and cannot be deleted. Member must be deleted first.
  • CANNOT_DELETE_CONTACT_WITH_BILLING_SUBSCRIPTION - Contact has a valid billing subscription and cannot be deleted.
  • CANNOT_DELETE_MEMBER_OWNER_OR_CONTRIBUTOR - Member cannot be deleted because it is the owner or a contributor. This can happen only if the request indicated to delete the member.
  • FAILED_DELETE_CONTACT_AFTER_MEMBER_DELETION - Member was deleted, but contact was not. This can happen only if the request indicated to delete the member.
  • 'FAILED_DELETE_CONTACT' - Contact could not be deleted.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Manage Members
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/bulk/contacts/delete

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostBulk Update Contacts

Updates the specified properties for multiple contacts. Fields that are included in fieldMask.paths are updated, while all other fields stay the same.

All contacts that meet the specified filter and search criteria are updated. To perform a dry run, use the intended filter options with Query Contacts.

When this endpoint is used, a bulk job is started and the job ID is returned. The job may not complete right away, depending on its size. The job's status can be retrieved with Get Bulk Job or List Bulk Jobs.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/bulk/contacts/update

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostBulk Label And Unlabel Contacts

Adds and removes labels from multiple contacts.

Labels are added to and removed from all contacts that meet the specified filter and search criteria. The request should contain a filter value or a search value, or both. To perform a dry run, use the intended filter options with Query Contacts.

When this endpoint is used, a bulk job is started and the job ID is returned. The job might not not complete right away, depending on its size. The job's status can be retrieved with Get Bulk Job or List Bulk Jobs.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/bulk/contacts/add-remove-labels

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetGet Contact

Retrieves a contact.

Getting Merged Contacts

When a source contact is merged with a target contact, the source contact is deleted. When calling Get Contact for a merged contact, you can use the source or target contact ID. In both bases, the target contact is returned.

This is supported only when calling Get Contact, and only for merged contacts. Deleted source contact IDs are not supported on any other endpoint.

Members are typically associated with a contact, each having a distinct member and contact ID. When passing the ID as a parameter, avoid presuming the IDs are identical since they represent separate entities.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/contacts/v4/contacts/{id}

Was this helpful?
Yes
No

Contact Created

Triggered when a contact is created.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.contact.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventobject

Event information.


Was this helpful?
Yes
No

Contact Updated

Triggered when a contact is updated.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.contact.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventobject

Event information.


Was this helpful?
Yes
No

Contact Merged

Triggered when one or more source contacts are merged into a target contact.

Merging contacts triggers these webhooks:

If your app handles the originating merge event, it can ignore update and delete events where originatedFrom is set to merge. When Contact Updated and Contact Deleted are not triggered from a merge, originatedFrom is omitted from their payloads.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.contact.


slugstring

Event name. Expected merged.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


actionEventobject

Event information.


Was this helpful?
Yes
No

Contact Deleted

Triggered when a contact is deleted.

If a contact is deleted as part of a merge, the originatedFrom property is sent as merge. Otherwise, originatedFrom is omitted.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Contacts
Read Members and Contacts - all read permissions
Manage Contacts
Manage Members and Contacts - all permissions
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.contact.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.


Was this helpful?
Yes
No