Contacts: Supported Filters, Sorting, and Search

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

Contact properties: Supported filters, sorting, and search

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).

Field	Supported Filters	Sortable	Searchable
`id`	`$eq`, `$ne`, `$in`, `$exists`
`createdDate`	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`	Sortable
`updatedDate`	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`
`lastActivity.activityDate`	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`	Sortable
`primaryInfo.email`	`$eq`, `$ne`, `$in`, `$exists`, `$startsWith`	Sortable
`primaryInfo.phone`	`$eq`, `$ne`, `$in`, `$exists`, `$startsWith`
`info.name.first`	`$eq`, `$ne`, `$in`, `$exists`, `$startsWith`	Sortable	Searchable
`info.name.last`	`$eq`, `$ne`, `$in`, `$exists`, `$startsWith`	Sortable	Searchable
`info.emails.email`	`$eq`, `$ne`, `$in`, `$exists`, `$startsWith`		Searchable
`info.phones.phone`	`$eq`, `$ne`, `$in`, `$exists`, `$startsWith`		Searchable
`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`, `$startsWith`	Sortable
`info.jobTitle`	`$eq`, `$ne`, `$in`, `$exists`, `$startsWith`	Sortable
`info.birthdate`	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`	Sortable
`info.locale`	`$eq`, `$ne`, `$in`, `$exists`
`info.labelKeys`	`$hasSome`, `$hasAll`
`info.locations`	`$hasSome`, `$hasAll`

Extended Fields: Supported filters, sorting, and search

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".

Field	Supported Filters	Sortable
`invoices.vatId`
`members.membershipStatus`	`$eq`,`$ne`,`$in`, `$nin`
`emailSubscriptions.deliverabilityStatus`	`$eq`,`$ne`,`$in`, `$nin`
`emailSubscriptions.subscriptionStatus`	`$eq`,`$ne`,`$in`, `$nin`
`emailSubscriptions.effectiveEmail`	`$exists`	Sortable

Custom Fields: Supported filters, sorting, and search

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/Format	Supported Filters	Sortable
String	`$eq`, `$ne`, `$in`, `$startsWith`	Sortable
Number	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`	Sortable
Date string in `YYYY-MM-DD` format	`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`	Sortable

Related content: API Query Language, Query Contacts

Was this helpful?

Yes

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 Type	Description
`GENERAL`	Visited the site.
`CONTACT_CREATED`	Became a new contact.
`MEMBER_LOGIN`	Logged in.
`MEMBER_REGISTER`	Requested site membership.
`MEMBER_STATUS_CHANGED`	Was approved, blocked, or unblocked.
`FORM_SUBMITTED`	Submitted a form.
`INBOX_FORM_SUBMITTED`	Started a chat.
`INBOX_PAYMENT_REQUEST_PAID`	Paid a payment request.
`INBOX_MESSAGE_TO_CUSTOMER`	Received a message from a site contributor.
`INBOX_MESSAGE_FROM_CUSTOMER`	Sent a new message to the site.
`NEWSLETTER_SUBSCRIPTION_FORM_SUBMITTED`	Subscribed to a site newsletter.
`NEWSLETTER_SUBSCRIPTION_UNSUBSCRIBE`	Unsubscribed from a site newsletter.
`ECOM_PURCHASE`	Made a Wix Stores purchase.
`ECOM_CART_ABANDON`	Abandoned their shopping cart.
`ECOM_CHECKOUT_BUYER`	Checked out shopping cart and submitted buyer info (but didn’t complete purchase yet).
`BOOKINGS_APPOINTMENT`	Booked an appointment.
`HOTELS_RESERVATION`	Made a Wix Hotels reservation.
`HOTELS_PURCHASE`	Paid for a Wix Hotels reservation.
`HOTELS_CONFIRMATION`	Confirmed a Wix Hotels reservation.
`HOTELS_CANCEL`	Canceled a Wix Hotels reservation.
`VIDEO_PURCHASE`	Purchased a video.
`VIDEO_RENT`	Rented a video.
`CASHIER_BUTTON_PURCHASE`	Made a purchase with a pay button.
`ARENA_NEW_LEAD`	Became a new Wix Marketplace lead.
`EVENTS_RSVP`	Responded that they're attending an event.
`INVOICE_PAY`	Paid an invoice.
`INVOICE_OVERDUE`	Contact's invoice is now overdue.
`PRICE_QUOTE_ACCEPT`	Accepted a price quote.
`PRICE_QUOTE_EXPIRE`	Contact’s price quote has expired.
`RESTAURANTS_ORDER`	Ordered food with Wix Restaurants.
`RESTAURANTS_RESERVATION`	Made a Wix Restaurants reservation.
`SHOUTOUT_OPEN`	Opened an email from the site.
`SHOUTOUT_CLICK`	Clicked a link in an email from the site.
`CONTACT_MERGED`	Merged with another contact.

Was this helpful?

Yes

Contact Object

Attributes

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.

sourceobject

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.

lastActivityobject

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

primaryInfoobject

Contact's primary phone and email.

pictureobject

Contact's profile picture. This can contain an image URL and a Wix Media image ID.

Deprecation Notice: This property has been replaced with info.picture and will be removed on March 31, 2022. If your app uses this property, we recommend updating your code as soon as possible.

infoobject

Contact's details.

Was this helpful?

Yes

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

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

GET

https://www.wixapis.com/contacts/v4/contacts

Was this helpful?

Yes

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

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/contacts

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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.

Permission Scopes

For app development, you must have one of the following permission scopes:

Manage Contacts

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

DELETE

https://www.wixapis.com/contacts/v4/contacts/{contactId}

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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.

Permission Scopes

For app development, you must have one of the following permission scopes:

Manage Contacts

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

PATCH

https://www.wixapis.com/contacts/v4/contacts/{contactId}

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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:

Contact Merged is triggered.
Contact Updated is triggered for the target contact. originatedFrom is set to merge.
Contact Deleted is triggered for each source contact. originatedFrom is set to merge.

Permission Scopes

For app development, you must have one of the following permission scopes:

Manage Contacts

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/contacts/{targetContactId}/merge

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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.

Permission Scopes

For app development, you must have one of the following permission scopes:

Manage Contacts

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/contacts/{targetContactId}/preview-merge

Was this helpful?

Yes

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).

Permission Scopes

For app development, you must have one of the following permission scopes:

Manage Contacts

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

DELETE

https://www.wixapis.com/contacts/v4/contacts/{contactId}/labels

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/contacts/query

Was this helpful?

Yes

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

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

GET

https://www.wixapis.com/contacts/v4/contacts/facets

Was this helpful?

Yes

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

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/contacts/facets/query

Was this helpful?

Yes

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.

Permission Scopes

For app development, you must have one of the following permission scopes:

Manage Contacts

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/bulk/contacts/delete

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/bulk/contacts/update

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST

https://www.wixapis.com/contacts/v4/bulk/contacts/add-remove-labels

Event Triggers

This method triggers the following events:

Was this helpful?

Yes

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.

Permission Scopes

For app development, you must have one of the following permission scopes:

Read Contacts

Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

GET

https://www.wixapis.com/contacts/v4/contacts/{id}

Was this helpful?

Yes

Contact Created

Triggered when a contact is created.

Permissions

CONTACTS.VIEW

Learn more about permissions.

Event Body

Event 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

Contact Updated

Permissions

CONTACTS.VIEW

Learn more about permissions.

Event Body

Event 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

Contact Merged

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

Merging contacts triggers these webhooks:

Contact Merged is triggered.
Contact Updated is triggered for the target contact. originatedFrom is set to merge.
Contact Deleted is triggered for each source contact. originatedFrom is set to merge.

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.

Permissions

CONTACTS.VIEW

Learn more about permissions.

Event Body

Event 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

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.

Permissions

CONTACTS.VIEW

Learn more about permissions.

Event Body

Event 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