> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # SearchContacts # Package: contacts # Namespace: Contacts # Method link: https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/search-contacts.md ## Permission Scopes: Read Contacts: SCOPE.DC-CONTACTS.READ-CONTACTS ## Introduction Retrieves a list of contacts using a free-text search combined with filtering and sorting. Search combines free-text matching with filtering, sorting, and cursor paging. To learn about the query syntax, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md). Searchable properties: `name.full`, `email.email`, `phone.phone`, `company.name`, `company.jobTitle`, `memberInfo.email`, and `memberInfo.profileInfo.nickname`. Name format: Set `nameFormat` to control how names are matched and ordered: - `BY_FIRST_NAME`: Orders by first name, then last name. - `BY_LAST_NAME`: Orders by last name, then first name. --- ## REST API ### Schema ``` Method: searchContacts Description: Retrieves a list of contacts using a free-text search combined with filtering and sorting. Search combines free-text matching with filtering, sorting, and cursor paging. To learn about the query syntax, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md). Searchable properties: `name.full`, `email.email`, `phone.phone`, `company.name`, `company.jobTitle`, `memberInfo.email`, and `memberInfo.profileInfo.nickname`. Name format: Set `nameFormat` to control how names are matched and ordered: - `BY_FIRST_NAME`: Orders by first name, then last name. - `BY_LAST_NAME`: Orders by last name, then first name. URL: https://www.wixapis.com/contacts/v5/contacts/search Method: POST Method parameters: param name: nameFormat | type: NameFormat | description: Name format types for sorting and searching. - enum: BY_FIRST_NAME - Names will be formatted starting with the first name followed by the last name. BY_LAST_NAME - Names will be formatted starting with the last name followed by the first name. param name: search | type: CursorSearch - name: cursorPaging | type: CursorPaging | description: Cursor paging options. Learn more about [cursor paging](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#cursor-paging). - name: limit | type: integer | description: Maximum number of items to return in the results. | validation: minimum 0, maximum 100, format int32 - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. | validation: maxLength 16000 - name: filter | type: object | description: Filter object. Learn more about the [filter section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-filter-section). - name: sort | type: array | description: List of sort objects. Learn more about the [sort section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-sort-section). | validation: maxItems 10 - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: aggregations | type: array | description: Aggregations, also known as faceted search. Lets you explore large amounts of data by displaying summaries about different partitions of the data, and narrow the navigation to a specific partition. | validation: maxItems 10 - ONE-OF: - name: value | type: ValueAggregation | description: Value aggregation. - ONE-OF: - name: includeOptions | type: IncludeMissingValuesOptions | description: Options for including missing values. Used only when `missingValues` is `INCLUDE`. - name: addToBucket | type: string | description: Custom name for the bucket that holds missing values. Default: `"N/A"` for string fields, `"0"` for integer fields, `"false"` for boolean fields. | validation: maxLength 20 - name: sortType | type: SortType | description: How to sort the aggregation results: by number of matches or by field value. - enum: - COUNT: Sorts by number of matches. - VALUE: Sorts by the field's value, alphabetically. - name: sortDirection | type: SortDirection | description: Sort direction: ascending or descending. - enum: - DESC: Sorts in descending order. - ASC: Sorts in ascending order. - name: limit | type: integer | description: Number of aggregations to return. Default: `10` | validation: format int32 - name: missingValues | type: MissingValues | description: Whether to include missing values in the aggregation results. Default: `EXCLUDE` - enum: - EXCLUDE: Missing values are excluded from the aggregation results. - INCLUDE: Missing values are included in the aggregation results. - name: range | type: RangeAggregation | description: Range aggregation. - name: buckets | type: array | description: Range buckets used for the aggregation. Each entity is placed in the first bucket whose range its value falls into. | validation: maxItems 50 - name: from | type: number | description: Inclusive lower bound of the range. Required if `to` isn't given. | validation: format double - name: to | type: number | description: Exclusive upper bound of the range. Required if `from` isn't given. | validation: format double - name: scalar | type: ScalarAggregation | description: Scalar aggregation. - name: type | type: ScalarType | description: Operator for the scalar aggregation. - enum: - COUNT_DISTINCT: Count of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: dateHistogram | type: DateHistogramAggregation | description: Date histogram aggregation. - name: interval | type: Interval | description: Interval for the date histogram aggregation. - enum: - YEAR: Yearly interval. - MONTH: Monthly interval. - WEEK: Weekly interval. - DAY: Daily interval. - HOUR: Hourly interval. - MINUTE: Minute interval. - SECOND: Second interval. - name: nested | type: NestedAggregation | description: Nested aggregation. - name: nestedAggregations | type: array | description: Flattened list of aggregations, where each next aggregation is nested within the previous one. | validation: minItems 2, maxItems 3 - ONE-OF: - name: value | type: ValueAggregation | description: Value aggregation. - name: range | type: RangeAggregation | description: Range aggregation. - name: scalar | type: ScalarAggregation | description: Scalar aggregation. - name: dateHistogram | type: DateHistogramAggregation | description: Date histogram aggregation. - name: name | type: string | description: User-defined name for the aggregation. Must be unique. Appears in the aggregation results. | validation: maxLength 100 - name: type | type: NestedAggregationType | description: Type of aggregation. Must match the aggregation type provided in the `kind` field. - enum: - VALUE: An aggregation where result buckets are dynamically built, one per unique value. - RANGE: An aggregation where you can define a set of ranges, each representing a bucket. - SCALAR: A single-value metric aggregation, such as min, max, sum, or avg. - DATE_HISTOGRAM: An aggregation where result buckets are dynamically built, one per time interval (hour, day, week, and so on). - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify the JSON path. | validation: maxLength 200 - name: name | type: string | description: User-defined name for the aggregation. Must be unique. Appears in the aggregation results. | validation: maxLength 100 - name: type | type: AggregationType | description: Type of aggregation. Must match the aggregation type provided in the `kind` field. - enum: - VALUE: An aggregation where result buckets are dynamically built, one per unique value. - RANGE: An aggregation where you can define a set of ranges, each representing a bucket. - SCALAR: A single-value metric aggregation, such as min, max, sum, or avg. - DATE_HISTOGRAM: An aggregation where result buckets are dynamically built, one per time interval (hour, day, week, and so on). - NESTED: Multi-level aggregation, where each next aggregation is nested within the previous one. - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify the JSON path. | validation: maxLength 200 - name: search | type: SearchDetails | description: Free text to match in searchable fields. - name: mode | type: Mode | description: How separate search terms in `expression` are combined. - enum: - OR: Any of the search terms must be present. - AND: All search terms must be present. - name: expression | type: string | description: Search term or expression. | validation: maxLength 100 - name: fields | type: array | description: Fields to search in. If empty, searches all searchable fields. Use dot notation to specify the JSON path. | validation: maxItems 20, maxLength 200 - name: fuzzy | type: boolean | description: Whether to use fuzzy search, which allows typos using a managed proximity algorithm. - name: timeZone | type: string | description: UTC offset or IANA time zone. Valid values are ISO 8601 UTC offsets, such as +02:00 or -06:00, and IANA time zone GUIDs, such as Europe/Rome. Affects the values returned by all filters and aggregations. You can override this behavior in a specific filter by providing timestamps that include a time zone. For example, `"2023-12-20T10:52:34.795Z"`. | validation: maxLength 50 Searchable fields: - field: assigneeId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: memberInfo.memberId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: source.appId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: source.userId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: timeZone | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: memberInfo.profileInfo.privacyStatus | operators: $eq, $exists, $in, $ne, $nin | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.status | operators: $eq, $exists, $in, $ne, $nin | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.userInfo.role | operators: $eq, $exists, $in, $ne, $nin | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.emailVerificationRequired | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: memberInfo.emailVerified | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: memberInfo.profileInfo.muted | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: memberInfo.profileInfo.reported | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: createdDate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: updatedDate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: lastActivity.date | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.sessionInfo.lastMobileLogin | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.sessionInfo.lastWebLogin | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.signupDate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: company.jobTitle | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: company.name | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: email.email | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: memberInfo.email | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: memberInfo.profileInfo.nickname | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: name.first | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: false - field: name.last | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: false - field: phone.phone | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: id | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: email.deliverabilityStatus | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: email.subscriptionStatus.status | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: phone.deliverabilityStatus | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: phone.subscriptionStatus.status | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: locale | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: none | aggregatable: true | searchable: false - field: phone.e164 | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: none | aggregatable: false | searchable: false - field: source.additionalInfo | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: none | aggregatable: true | searchable: false - field: locationIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: memberInfo.groupInfo.groupIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: memberInfo.sessionInfo.mobileAppNames | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: segmentIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: tags.privateTags.tagIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: addresses.address.country | operators: $exists, $hasAll, $hasSome | sort: none | aggregatable: true | searchable: false - field: addresses.address.subdivision | operators: $exists, $hasAll, $hasSome | sort: none | aggregatable: true | searchable: false - field: addresses.recipient.phone | operators: $exists, $hasAll, $hasSome | sort: none | aggregatable: false | searchable: false - field: additionalEmails.email | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: additionalPhones.e164 | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: additionalPhones.phone | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.address.addressLine | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.address.city | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.address.postalCode | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.address.streetAddress.name | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.address.subdivisionFullname | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: true | searchable: false - field: addresses.recipient.company | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.recipient.firstName | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.recipient.lastName | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: birthdate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: false | searchable: false - field: name.full | operators: none | sort: none | aggregatable: false | searchable: true Return type: SearchContactsResponse - name: contacts | type: array | description: Retrieved contacts. - name: id | type: string | description: Contact GUID. | validation: format GUID, immutable - name: revision | type: string | description: Revision number, which increments by 1 each time the Contact is updated. To prevent conflicting changes, the current revision must be passed when updating the Contact. Ignored when creating a Contact. | validation: format int64 - name: createdDate | type: string | description: Date and time the contact was created. | validation: format date-time, immutable - name: updatedDate | type: string | description: Date and time the contact was last updated. | validation: format date-time - name: externalId | type: string | description: Contact external GUID. Used to identify contacts from external systems. This field can only be set once and can't be updated after creation. | validation: maxLength 100 - name: name | type: ContactName | description: Contact's name information including first and last name. - name: first | type: string | description: Contact's first name. | validation: maxLength 1000 - name: last | type: string | description: Contact's last name. | validation: maxLength 1000 - name: email | type: ContactEmail | description: The main email of the contact with subscription status and deliverability information. This email is used for contact matching and deduplication logic. - name: email | type: string | description: Main email address for the contact. Used for communication and contact matching. Stored in normalized form: leading and trailing whitespace is trimmed and the address is lowercased. | validation: maxLength 320, format EMAIL - name: subscriptionStatus | type: ContactSubscription | description: Indicates the recipient's opt-in or opt-out status for marketing emails. This field is read-only and managed by the subscription system. Updates are eventually consistent, reflecting marketing consent changes after they're processed. - name: status | type: SubscriptionStatus | description: Indicates the recipient's opt-in or opt-out status for marketing communications. - `NO_SUBSCRIPTION_STATUS`: No status exists. Used when a phone is not a valid E164 number. - `NOT_SET`: No subscription status specified. Default value. - `PENDING`: Subscription confirmation was requested, but recipient hasn't confirmed yet. - `SUBSCRIBED`: Recipient has explicitly opted in to receive marketing communications. - `UNSUBSCRIBED`: Recipient has opted out of marketing communications. - enum: NO_SUBSCRIPTION_STATUS, NOT_SET, PENDING, SUBSCRIBED, UNSUBSCRIBED - name: updatedDate | type: string | description: Date and time when the subscription status was last updated. | validation: format date-time - name: deliverabilityStatus | type: EmailDeliverabilityStatus | description: Indicates the last reported delivery status of emails sent to this address. This field is read-only and updated automatically by the email delivery system. - `NOT_SET`: No delivery status reported. Default value. - `VALID`: Emails are being successfully delivered to this address. - `BOUNCED`: The last email to this address bounced or was rejected by the recipient's email server. - `SPAM_COMPLAINT`: Recipient registered a spam complaint with their email provider. - `INACTIVE`: Multiple emails have been delivered without any engagement from the recipient. - enum: NOT_SET, VALID, BOUNCED, SPAM_COMPLAINT, INACTIVE - name: additionalEmails | type: array | description: Additional emails of the contact. These emails do not affect subscription status or contact matching/deduplication. The main email field must be set before additional emails can be added. | validation: maxItems 10 - name: email | type: string | description: Additional email address for the contact. Does not affect subscription status or contact matching logic. | validation: maxLength 320, format EMAIL - name: phone | type: ContactPhone | description: The main phone of the contact with subscription status and deliverability information. This phone is used for contact matching and deduplication logic. At least one of name, email, or phone is required for contact creation. - name: tag | type: PhoneTag | description: Phone type classification. Helps categorize the phone number's purpose. Default: `OTHER` - enum: OTHER, MAIN, HOME, MOBILE, WORK, FAX - name: phone | type: string | description: Primary phone number for the contact. Used for communication and contact matching. | validation: minLength 1, maxLength 50 - name: e164 | type: string | description: Phone number in [ITU E.164 international](https://www.itu.int/rec/T-REC-E.164/) format (e.g., +12345550123). This field is automatically generated from the phone field if it represents a valid E.164 number. | validation: maxLength 50 - name: subscriptionStatus | type: ContactSubscription | description: Indicates the recipient's opt-in or opt-out status for SMS/text message marketing. This field is read-only and managed by the subscription system. Updates are eventually consistent, reflecting marketing consent changes after they're processed. - name: deliverabilityStatus | type: PhoneDeliverabilityStatus | description: Indicates the delivery status for SMS messages sent to this phone number. This field is read-only and updated automatically by the SMS delivery system. - `NO_PHONE_DELIVERABILITY_STATUS`: No status exists. Used when the phone is not a valid E164 number. - `NOT_SET`: No delivery status reported. Default when the phone is a valid E164 number. - `VALID`: Last message was sent and delivered successfully. - `INVALID`: The number is invalid (landline, number disconnected, etc.). - enum: NO_PHONE_DELIVERABILITY_STATUS, NOT_SET, VALID, INVALID - name: additionalPhones | type: array | description: Additional phones of the contact. These phones do not affect subscription status or contact matching/deduplication. The main phone field must be set before additional phones can be added. | validation: maxItems 10 - name: tag | type: PhoneTag | description: Phone type classification for the additional phone number. Default: `OTHER` - name: phone | type: string | description: Additional phone number for the contact. Does not affect subscription status or contact matching logic. | validation: minLength 1, maxLength 50 - name: e164 | type: string | description: Additional phone number in [ITU E.164 international](https://www.itu.int/rec/T-REC-E.164/) format (e.g., +12345550123). This field is automatically generated from the phone field if it represents a valid E.164 number. | validation: maxLength 50 - name: addresses | type: array | description: Contact's physical addresses. Each address can be tagged (HOME, WORK, BILLING, SHIPPING, OTHER) and one can be set as default. If no address is marked as default, the first address automatically becomes the default. | validation: maxItems 50 - name: tag | type: AddressTag | description: Address type classification. Helps categorize the address purpose. Default: `OTHER` - enum: OTHER, HOME, WORK, BILLING, SHIPPING - name: address | type: Address | description: Physical address information including street, city, country, and postal code. Contains structured address data following common address formatting standards. - ONE-OF: - name: streetAddress | type: StreetAddress | description: Street address object, with number and name in separate fields. - name: number | type: string | description: Street number. | validation: maxLength 100 - name: name | type: string | description: Street name. | validation: maxLength 300 - name: apt | type: string | description: Apartment number. | validation: maxLength 50 - name: formattedAddressLine | type: string | description: Optional formatted version of the street address line. | validation: maxLength 2000 - name: addressLine | type: string | description: Main address line, usually street and number, as free text. | validation: maxLength 1000 - name: country | type: string | description: 2-letter country code in an [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. | validation: format COUNTRY - name: subdivision | type: string | description: Subdivision shorthand. Usually, a short code (2 or 3 letters) that represents a state, region, prefecture, or province. For example, `NY`. | validation: format SUBDIVISION - name: city | type: string | description: City name. | validation: maxLength 300 - name: postalCode | type: string | description: Postal or zip code. | validation: maxLength 100 - name: addressLine2 | type: string | description: Free text providing more detailed address information, such as apartment, suite, or floor. | validation: maxLength 1000 - name: formattedAddress | type: string | description: Human-readable address string. If not provided, the value is generated from the available address data. | validation: maxLength 2000 - name: hint | type: string | description: Instructions to help someone find the address, such as landmarks or where the entrance is. | validation: maxLength 200 - name: geocode | type: AddressLocation | description: Coordinates of the physical address. - name: latitude | type: number | description: Address latitude. | validation: minimum -90, maximum 90, format double - name: longitude | type: number | description: Address longitude. | validation: minimum -180, maximum 180, format double - name: countryFullname | type: string | description: Full country name. | validation: maxLength 100 - name: subdivisions | type: array | description: Hierarchical list of subdivisions, where the first array item is the highest level of hierarchy, and so on. | validation: maxItems 6 - name: code | type: string | description: Subdivision short code. | validation: maxLength 20 - name: name | type: string | description: Full subdivision name. | validation: maxLength 100 - name: type | type: SubdivisionType | description: Subdivision level. - enum: - UNKNOWN_SUBDIVISION_TYPE: - ADMINISTRATIVE_AREA_LEVEL_1: State. - ADMINISTRATIVE_AREA_LEVEL_2: County. - ADMINISTRATIVE_AREA_LEVEL_3: City/town. - ADMINISTRATIVE_AREA_LEVEL_4: Neighborhood/quarter. - ADMINISTRATIVE_AREA_LEVEL_5: Street/block. - COUNTRY: Equivalent to `ADMINISTRATIVE_AREA_LEVEL_0`. Indicates the national political entity, and is typically the highest order type returned by the Geocoder. - name: typeInfo | type: string | description: Free text description of subdivision type. Examples: `"state"`, `"province"`, `"prefecture"`. | validation: maxLength 100 - name: subdivisionFullname | type: string | description: Subdivision full name. | validation: maxLength 100 - name: defaultAddress | type: boolean | description: Whether this address is the contact's default address. Only one address can be designated as default per contact. If no address is explicitly set as default, the first address automatically becomes the default. - name: id | type: string | description: Address GUID. | validation: format GUID - name: recipient | type: Recipient | description: Address recipient information for delivery purposes. - name: firstName | type: string | description: Recipient's first name. | validation: maxLength 1000 - name: lastName | type: string | description: Recipient's last name. | validation: maxLength 1000 - name: company | type: string | description: Recipient's company name. | validation: maxLength 1000 - name: phone | type: string | description: Recipient's phone number. | validation: minLength 1, maxLength 50 - name: company | type: ContactCompany | description: Contact's company information including company name and job title. - name: name | type: string | description: Contact's company name. | validation: maxLength 1000 - name: jobTitle | type: string | description: Contact's job title. | validation: maxLength 1000 - name: locale | type: string | description: Locale in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. Typically, this is a lowercase 2-letter language code, followed by a hyphen, followed by an uppercase 2-letter country code. For example, `en-US` for U.S. English, and `de-DE` for Germany German. | validation: format LANGUAGE_TAG - name: birthdate | type: string | description: Birth date in `YYYY-MM-DD` format. For example, `2020-03-15`. | validation: format LOCAL_DATE - name: timeZone | type: string | description: IANA time zone identifier for the contact's location. Valid values are IANA time zone GUIDs, such as 'Europe/Rome' or 'America/New_York'. | validation: maxLength 50 - name: assigneeId | type: string | description: Site contributor user GUID assigned to manage communication with this contact. Must be a valid GUGUID referencing an existing site contributor. Only one assignee can be set per contact. | validation: format GUID - name: locationIds | type: array | description: List of business location GUIDs associated with this contact. Used for multi-location businesses to organize contacts by physical business locations. Each GUID must be a valid GUGUID referencing an existing business location. | validation: maxItems 50, format GUID - name: image | type: Image | description: Contact's profile image. - name: id | type: string | description: Media Manager image GUID. | validation: maxLength 255 - name: url | type: string | description: Image URL. The URL is valid until the date in `urlExpirationDate`. | validation: maxLength 2048 - name: height | type: integer | description: Original image height. - name: width | type: integer | description: Original image width. - name: altText | type: string | description: Image alt text. | validation: maxLength 100 - name: urlExpirationDate | type: string | description: Image URL expiration date (when relevant). | validation: format date-time - name: sizeInBytes | type: string | description: Image size in bytes. | validation: format DECIMAL_VALUE, decimalValue {"gte":"0","maxScale":2} - name: source | type: ContactSource | description: Details about the origin of the contact. This field is immutable and set automatically when the contact is created. | validation: immutable - name: userId | type: string | description: GUID of the user who created this contact. | validation: format GUID, immutable - name: appId | type: string | description: GUID of the application that created this contact. | validation: format GUID, immutable - name: additionalInfo | type: string | description: Additional information about the contact's origin or creation context. | validation: maxLength 1000, immutable - name: lastActivity | type: ContactActivity | description: Details about the contact's most recent activity on the site. Includes activity date and template GUID. This field is read-only and updated automatically. - name: date | type: string | description: Date and time when the contact's most recent activity occurred. | validation: format date-time - name: templateId | type: string | description: GUID of the activity template that defines the type of activity performed. References a template in the contacts activity log system. | validation: format GUID - name: segmentIds | type: array | description: IDs of the segments the contact belongs to. Segments are used for organizing and targeting groups of contacts. | validation: maxItems 60, format GUID - name: memberInfo | type: MemberInfo | description: Contact's site membership information including member GUID, status, and profile details. This field is read-only and populated automatically when the contact is also a site member. Updates are eventually consistent: changes to the underlying member, identity, or profile are reflected after the corresponding events are processed. - name: memberId | type: string | description: Member GUID. | validation: format GUID - name: signupDate | type: string | description: Date and time the member signed up. | validation: format date-time - name: email | type: string | description: Email the member uses to log in. | validation: format EMAIL - name: emailVerified | type: boolean | description: Whether the email is verified. - name: emailVerificationRequired | type: boolean | description: Whether the member is required to verify their email before they can log in. - name: status | type: MemberStatus | description: Member status. - `PENDING`: Member created and is waiting for approval by site owner. - `ACTIVE`: Member can log in to the site. - `BLOCKED`: Member is blocked and cannot log in to the site. - `OFFLINE`: Member is a [managed writer](https://support.wix.com/en/article/wix-blog-adding-managed-writers-to-your-blog) for the site blog and cannot log in to the site. - enum: PENDING, ACTIVE, BLOCKED, OFFLINE - name: profileInfo | type: ProfileInfo | description: Information about the member's public profile. - name: nickname | type: string | description: Member's nickname. | validation: maxLength 255 - name: privacyStatus | type: PrivacyStatus | description: Whether the member's profile is visible to other site members and visitors. - enum: PRIVATE, PUBLIC - name: reported | type: boolean | description: Whether the member has been reported by another member. - name: muted | type: boolean | description: Whether the member has been muted and can't post or comment on the site. - name: photo | type: Image | description: Member's profile photo. - name: userInfo | type: UserInfo | description: Information about the member's user account. - name: userId | type: string | description: User GUID. | validation: format GUID - name: role | type: Role | description: Member's role on the site. - enum: OWNER, CONTRIBUTOR, MEMBER - name: sessionInfo | type: SessionInfo | description: Information about the member's login sessions. - name: lastWebLogin | type: string | description: Date and time the member last logged in to the site from a browser. | validation: format date-time - name: lastMobileLogin | type: string | description: Date and time the member last logged in from one of the mobile apps. | validation: format date-time - name: mobileAppNames | type: array | description: Mobile apps the member has ever logged in to. | validation: maxItems 50, maxLength 50 - name: groupInfo | type: GroupInfo | description: Information about the groups the member belongs to. - name: groupIds | type: array | description: IDs of the groups the member belongs to. | validation: maxItems 1000, format GUID - name: tags | type: PrivateTags | description: Tags assigned to the contact for organization and filtering. - name: privateTags | type: TagList | description: Tags that require an additional permission to access, normally not given to site members or visitors. - name: tagIds | type: array | description: A list of tag GUIDs. To create a tag, use the [Tags API](https://dev.wix.com/docs/api-reference/business-management/tags/introduction.md) with the contacts FQDN: `wix.contacts.*.contact`. | validation: maxItems 1000, maxLength 5 - name: extendedFields | type: ExtendedFields | description: Extended fields for storing custom contact data beyond the standard fields. Allows adding custom properties specific to business needs. To define a custom extended field, use the [Schema Service API](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/about-the-data-extension-schema-api.md) with the contacts FQDN: `wix.contacts.*.contact`. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the current page. | validation: format int32 - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. | validation: maxLength 16000 - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. | validation: maxLength 16000 - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. - name: total | type: integer | description: Total number of items matching the filter. Available only on the first page of Search results, not included in Query or List results. If the Search results span multiple pages, the value of `total` can exceed the number of items returned on the first page. | validation: format int32 - name: aggregationData | type: AggregationData | description: Aggregation data. - name: results | type: array | description: Results of the requested aggregations. | validation: maxItems 10000 - ONE-OF: - name: values | type: ValueResults | description: Value aggregation results. - name: results | type: array | description: Value aggregation results. | validation: maxItems 250 - name: value | type: string | description: Value of the field. | validation: maxLength 100 - name: count | type: integer | description: Count of entities with this value. - name: ranges | type: RangeResults | description: Range aggregation results. - name: results | type: array | description: Range results, returned in the same order as requested. | validation: maxItems 50 - name: from | type: number | description: Inclusive lower bound of the range. | validation: format double - name: to | type: number | description: Exclusive upper bound of the range. | validation: format double - name: count | type: integer | description: Count of entities in this range. - name: scalar | type: ScalarResult | description: Scalar aggregation results. - name: type | type: ScalarType | description: Type of scalar aggregation. - enum: - COUNT_DISTINCT: Count of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: value | type: number | description: Value of the scalar aggregation. - name: dateHistogram | type: DateHistogramResults | description: Date histogram aggregation results. - name: results | type: array | description: Date histogram aggregation results. | validation: maxItems 200 - name: value | type: string | description: Date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. | validation: maxLength 100 - name: count | type: integer | description: Count of documents in the bucket. - name: nested | type: NestedResults | description: Nested aggregation results. - name: results | type: array | description: Nested aggregation results. | validation: maxItems 1000 - name: results | type: Map | description: Nested aggregation results, keyed by aggregation name. | validation: format map - ONE-OF: - name: value | type: ValueResult | description: Value aggregation result. - name: value | type: string | description: Value of the field. | validation: maxLength 1000 - name: count | type: integer | description: Count of entities with this value. | validation: format int32 - name: range | type: RangeResult | description: Range aggregation result. - name: from | type: number | description: Inclusive lower bound of the range. | validation: format double - name: to | type: number | description: Exclusive upper bound of the range. | validation: format double - name: count | type: integer | description: Count of entities in this range. | validation: format int32 - name: scalar | type: ScalarResult | description: Scalar aggregation result. - name: value | type: number | description: Value of the scalar aggregation. - name: dateHistogram | type: ValueResult | description: Date histogram aggregation result. - name: name | type: string | description: User-defined name of the aggregation, as provided in the search request. | validation: maxLength 100 - name: type | type: AggregationType | description: Type of aggregation. Matches the `kind` provided in the search request. - enum: - VALUE: An aggregation where result buckets are dynamically built, one per unique value. - RANGE: An aggregation where you can define a set of ranges, each representing a bucket. - SCALAR: A single-value metric aggregation, such as min, max, sum, or avg. - DATE_HISTOGRAM: An aggregation where result buckets are dynamically built, one per time interval (hour, day, week, and so on). - NESTED: Multi-level aggregation, where each next aggregation is nested within the previous one. - name: fieldPath | type: string | description: Field to aggregate by, as provided in the search request. | validation: maxLength 200 ``` ### Examples ### Search contacts with text query Searches contacts using free-text in search.search.expression with sort and cursor paging. ```curl curl -X POST \ 'https://www.wixapis.com/contacts/v5/contacts/search' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "search": { "search": { "expression": "John", "mode": "OR", "fuzzy": true }, "sort": [ { "fieldName": "createdDate", "order": "ASC" } ], "cursorPaging": { "limit": 10 } }, "nameFormat": "BY_FIRST_NAME" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.crm.contactsV5.searchContacts(search, options) Description: Retrieves a list of contacts using a free-text search combined with filtering and sorting. Search combines free-text matching with filtering, sorting, and cursor paging. To learn about the query syntax, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md). Searchable properties: `name.full`, `email.email`, `phone.phone`, `company.name`, `company.jobTitle`, `memberInfo.email`, and `memberInfo.profileInfo.nickname`. Name format: Set `nameFormat` to control how names are matched and ordered: - `BY_FIRST_NAME`: Orders by first name, then last name. - `BY_LAST_NAME`: Orders by last name, then first name. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: search Method parameters: param name: options | type: SearchContactsOptions none - name: nameFormat | type: NameFormat | description: Name Format for sorting and searching. When sorting by `displayName`, the returned contacts are ordered by first and last names, by default. Alternatively, when sorting by `displayName` with `BY_LAST_NAME`, the returned contacts are ordered by last and first names. For contacts that do not have names, sorting is by email or phone. When searching by `name.full`, the contacts returned are matched and ordered by first and last names. Alternatively, when searching by `name.full` with `BY_LAST_NAME`, the contacts returned are matched and ordered by last and first names. - enum: - BY_FIRST_NAME: Names will be formatted starting with the first name followed by the last name. - BY_LAST_NAME: Names will be formatted starting with the last name followed by the first name. param name: search | type: CursorSearch | required: true - name: cursorPaging | type: CursorPaging | description: Cursor paging options. Learn more about [cursor paging](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#cursor-paging). - name: limit | type: integer | description: Maximum number of items to return in the results. | validation: minimum 0, maximum 100, format int32 - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. | validation: maxLength 16000 - name: filter | type: object | description: Filter object. Learn more about the [filter section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-filter-section). - name: sort | type: array | description: List of sort objects. Learn more about the [sort section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-sort-section). | validation: maxItems 10 - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: aggregations | type: array | description: Aggregations, also known as faceted search. Lets you explore large amounts of data by displaying summaries about different partitions of the data, and narrow the navigation to a specific partition. | validation: maxItems 10 - ONE-OF: - name: value | type: ValueAggregation | description: Value aggregation. - ONE-OF: - name: includeOptions | type: IncludeMissingValuesOptions | description: Options for including missing values. Used only when `missingValues` is `INCLUDE`. - name: addToBucket | type: string | description: Custom name for the bucket that holds missing values. Default: `"N/A"` for string fields, `"0"` for integer fields, `"false"` for boolean fields. | validation: maxLength 20 - name: sortType | type: SortType | description: How to sort the aggregation results: by number of matches or by field value. - enum: - COUNT: Sorts by number of matches. - VALUE: Sorts by the field's value, alphabetically. - name: sortDirection | type: SortDirection | description: Sort direction: ascending or descending. - enum: - DESC: Sorts in descending order. - ASC: Sorts in ascending order. - name: limit | type: integer | description: Number of aggregations to return. Default: `10` | validation: format int32 - name: missingValues | type: MissingValues | description: Whether to include missing values in the aggregation results. Default: `EXCLUDE` - enum: - EXCLUDE: Missing values are excluded from the aggregation results. - INCLUDE: Missing values are included in the aggregation results. - name: range | type: RangeAggregation | description: Range aggregation. - name: buckets | type: array | description: Range buckets used for the aggregation. Each entity is placed in the first bucket whose range its value falls into. | validation: maxItems 50 - name: from | type: number | description: Inclusive lower bound of the range. Required if `to` isn't given. - name: to | type: number | description: Exclusive upper bound of the range. Required if `from` isn't given. - name: scalar | type: ScalarAggregation | description: Scalar aggregation. - name: type | type: ScalarType | description: Operator for the scalar aggregation. - enum: - COUNT_DISTINCT: Count of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: dateHistogram | type: DateHistogramAggregation | description: Date histogram aggregation. - name: interval | type: Interval | description: Interval for the date histogram aggregation. - enum: - YEAR: Yearly interval. - MONTH: Monthly interval. - WEEK: Weekly interval. - DAY: Daily interval. - HOUR: Hourly interval. - MINUTE: Minute interval. - SECOND: Second interval. - name: nested | type: NestedAggregation | description: Nested aggregation. - name: nestedAggregations | type: array | description: Flattened list of aggregations, where each next aggregation is nested within the previous one. | validation: minItems 2, maxItems 3 - ONE-OF: - name: value | type: ValueAggregation | description: Value aggregation. - name: range | type: RangeAggregation | description: Range aggregation. - name: scalar | type: ScalarAggregation | description: Scalar aggregation. - name: dateHistogram | type: DateHistogramAggregation | description: Date histogram aggregation. - name: name | type: string | description: User-defined name for the aggregation. Must be unique. Appears in the aggregation results. | validation: maxLength 100 - name: type | type: NestedAggregationType | description: Type of aggregation. Must match the aggregation type provided in the `kind` field. - enum: - VALUE: An aggregation where result buckets are dynamically built, one per unique value. - RANGE: An aggregation where you can define a set of ranges, each representing a bucket. - SCALAR: A single-value metric aggregation, such as min, max, sum, or avg. - DATE_HISTOGRAM: An aggregation where result buckets are dynamically built, one per time interval (hour, day, week, and so on). - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify the JSON path. | validation: maxLength 200 - name: name | type: string | description: User-defined name for the aggregation. Must be unique. Appears in the aggregation results. | validation: maxLength 100 - name: type | type: AggregationType | description: Type of aggregation. Must match the aggregation type provided in the `kind` field. - enum: - VALUE: An aggregation where result buckets are dynamically built, one per unique value. - RANGE: An aggregation where you can define a set of ranges, each representing a bucket. - SCALAR: A single-value metric aggregation, such as min, max, sum, or avg. - DATE_HISTOGRAM: An aggregation where result buckets are dynamically built, one per time interval (hour, day, week, and so on). - NESTED: Multi-level aggregation, where each next aggregation is nested within the previous one. - name: fieldPath | type: string | description: Field to aggregate by. Use dot notation to specify the JSON path. | validation: maxLength 200 - name: search | type: SearchDetails | description: Free text to match in searchable fields. - name: mode | type: Mode | description: How separate search terms in `expression` are combined. - enum: - OR: Any of the search terms must be present. - AND: All search terms must be present. - name: expression | type: string | description: Search term or expression. | validation: maxLength 100 - name: fields | type: array | description: Fields to search in. If empty, searches all searchable fields. Use dot notation to specify the JSON path. | validation: maxItems 20, maxLength 200 - name: fuzzy | type: boolean | description: Whether to use fuzzy search, which allows typos using a managed proximity algorithm. - name: timeZone | type: string | description: UTC offset or IANA time zone. Valid values are ISO 8601 UTC offsets, such as +02:00 or -06:00, and IANA time zone GUIDs, such as Europe/Rome. Affects the values returned by all filters and aggregations. You can override this behavior in a specific filter by providing timestamps that include a time zone. For example, `"2023-12-20T10:52:34.795Z"`. | validation: maxLength 50 Searchable fields: - field: assigneeId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: memberInfo.memberId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: source.appId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: source.userId | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: timeZone | operators: $eq, $exists, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: memberInfo.profileInfo.privacyStatus | operators: $eq, $exists, $in, $ne, $nin | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.status | operators: $eq, $exists, $in, $ne, $nin | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.userInfo.role | operators: $eq, $exists, $in, $ne, $nin | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.emailVerificationRequired | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: memberInfo.emailVerified | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: memberInfo.profileInfo.muted | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: memberInfo.profileInfo.reported | operators: $eq, $ne | sort: none | aggregatable: true | searchable: false - field: _createdDate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: _updatedDate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: lastActivity.date | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.sessionInfo.lastMobileLogin | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.sessionInfo.lastWebLogin | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: memberInfo.signupDate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: true | searchable: false - field: company.jobTitle | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: company.name | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: email.email | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: memberInfo.email | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: memberInfo.profileInfo.nickname | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: name.first | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: false - field: name.last | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: false - field: phone.phone | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: ASC, DESC | aggregatable: false | searchable: true - field: _id | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: email.deliverabilityStatus | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: email.subscriptionStatus.status | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: phone.deliverabilityStatus | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: phone.subscriptionStatus.status | operators: $eq, $in, $ne, $nin | sort: none | aggregatable: true | searchable: false - field: locale | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: none | aggregatable: true | searchable: false - field: phone.e164 | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: none | aggregatable: false | searchable: false - field: source.additionalInfo | operators: $eq, $exists, $in, $ne, $nin, $startsWith | sort: none | aggregatable: true | searchable: false - field: locationIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: memberInfo.groupInfo.groupIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: memberInfo.sessionInfo.mobileAppNames | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: segmentIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: tags.privateTags.tagIds | operators: $exists, $hasAll, $hasSome, $isEmpty | sort: none | aggregatable: true | searchable: false - field: addresses.address.country | operators: $exists, $hasAll, $hasSome | sort: none | aggregatable: true | searchable: false - field: addresses.address.subdivision | operators: $exists, $hasAll, $hasSome | sort: none | aggregatable: true | searchable: false - field: addresses.recipient.phone | operators: $exists, $hasAll, $hasSome | sort: none | aggregatable: false | searchable: false - field: additionalEmails.email | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: additionalPhones.e164 | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: additionalPhones.phone | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.address.city | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: true | searchable: false - field: addresses.address.postalCode | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: true | searchable: false - field: addresses.recipient.company | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.recipient.firstName | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: addresses.recipient.lastName | operators: $exists, $hasAll, $hasSome, $startsWith | sort: none | aggregatable: false | searchable: false - field: birthdate | operators: $eq, $gt, $gte, $lt, $lte, $ne | sort: ASC, DESC | aggregatable: false | searchable: false Return type: PROMISE - name: contacts | type: array | description: Retrieved contacts. - name: _id | type: string | description: Contact GUID. | validation: format GUID, immutable - name: revision | type: string | description: Revision number, which increments by 1 each time the Contact is updated. To prevent conflicting changes, the current revision must be passed when updating the Contact. Ignored when creating a Contact. | validation: format int64 - name: _createdDate | type: Date | description: Date and time the contact was created. | validation: immutable - name: _updatedDate | type: Date | description: Date and time the contact was last updated. - name: externalId | type: string | description: Contact external GUID. Used to identify contacts from external systems. This field can only be set once and can't be updated after creation. | validation: maxLength 100 - name: name | type: ContactName | description: Contact's name information including first and last name. - name: first | type: string | description: Contact's first name. | validation: maxLength 1000 - name: last | type: string | description: Contact's last name. | validation: maxLength 1000 - name: email | type: ContactEmail | description: The main email of the contact with subscription status and deliverability information. This email is used for contact matching and deduplication logic. - name: email | type: string | description: Main email address for the contact. Used for communication and contact matching. Stored in normalized form: leading and trailing whitespace is trimmed and the address is lowercased. | validation: maxLength 320, format EMAIL - name: subscriptionStatus | type: ContactSubscription | description: Indicates the recipient's opt-in or opt-out status for marketing emails. This field is read-only and managed by the subscription system. Updates are eventually consistent, reflecting marketing consent changes after they're processed. - name: status | type: SubscriptionStatus | description: Indicates the recipient's opt-in or opt-out status for marketing communications. - `NO_SUBSCRIPTION_STATUS`: No status exists. Used when a phone is not a valid E164 number. - `NOT_SET`: No subscription status specified. Default value. - `PENDING`: Subscription confirmation was requested, but recipient hasn't confirmed yet. - `SUBSCRIBED`: Recipient has explicitly opted in to receive marketing communications. - `UNSUBSCRIBED`: Recipient has opted out of marketing communications. - enum: NO_SUBSCRIPTION_STATUS, NOT_SET, PENDING, SUBSCRIBED, UNSUBSCRIBED - name: _updatedDate | type: Date | description: Date and time when the subscription status was last updated. - name: deliverabilityStatus | type: EmailDeliverabilityStatus | description: Indicates the last reported delivery status of emails sent to this address. This field is read-only and updated automatically by the email delivery system. - `NOT_SET`: No delivery status reported. Default value. - `VALID`: Emails are being successfully delivered to this address. - `BOUNCED`: The last email to this address bounced or was rejected by the recipient's email server. - `SPAM_COMPLAINT`: Recipient registered a spam complaint with their email provider. - `INACTIVE`: Multiple emails have been delivered without any engagement from the recipient. - enum: NOT_SET, VALID, BOUNCED, SPAM_COMPLAINT, INACTIVE - name: additionalEmails | type: array | description: Additional emails of the contact. These emails do not affect subscription status or contact matching/deduplication. The main email field must be set before additional emails can be added. | validation: maxItems 10 - name: email | type: string | description: Additional email address for the contact. Does not affect subscription status or contact matching logic. | validation: maxLength 320, format EMAIL - name: phone | type: ContactPhone | description: The main phone of the contact with subscription status and deliverability information. This phone is used for contact matching and deduplication logic. At least one of name, email, or phone is required for contact creation. - name: tag | type: PhoneTag | description: Phone type classification. Helps categorize the phone number's purpose. Default: `OTHER` - enum: OTHER, MAIN, HOME, MOBILE, WORK, FAX - name: phone | type: string | description: Primary phone number for the contact. Used for communication and contact matching. | validation: minLength 1, maxLength 50 - name: e164 | type: string | description: Phone number in [ITU E.164 international](https://www.itu.int/rec/T-REC-E.164/) format (e.g., +12345550123). This field is automatically generated from the phone field if it represents a valid E.164 number. | validation: maxLength 50 - name: subscriptionStatus | type: ContactSubscription | description: Indicates the recipient's opt-in or opt-out status for SMS/text message marketing. This field is read-only and managed by the subscription system. Updates are eventually consistent, reflecting marketing consent changes after they're processed. - name: deliverabilityStatus | type: PhoneDeliverabilityStatus | description: Indicates the delivery status for SMS messages sent to this phone number. This field is read-only and updated automatically by the SMS delivery system. - `NO_PHONE_DELIVERABILITY_STATUS`: No status exists. Used when the phone is not a valid E164 number. - `NOT_SET`: No delivery status reported. Default when the phone is a valid E164 number. - `VALID`: Last message was sent and delivered successfully. - `INVALID`: The number is invalid (landline, number disconnected, etc.). - enum: NO_PHONE_DELIVERABILITY_STATUS, NOT_SET, VALID, INVALID - name: additionalPhones | type: array | description: Additional phones of the contact. These phones do not affect subscription status or contact matching/deduplication. The main phone field must be set before additional phones can be added. | validation: maxItems 10 - name: tag | type: PhoneTag | description: Phone type classification for the additional phone number. Default: `OTHER` - name: phone | type: string | description: Additional phone number for the contact. Does not affect subscription status or contact matching logic. | validation: minLength 1, maxLength 50 - name: e164 | type: string | description: Additional phone number in [ITU E.164 international](https://www.itu.int/rec/T-REC-E.164/) format (e.g., +12345550123). This field is automatically generated from the phone field if it represents a valid E.164 number. | validation: maxLength 50 - name: addresses | type: array | description: Contact's physical addresses. Each address can be tagged (HOME, WORK, BILLING, SHIPPING, OTHER) and one can be set as default. If no address is marked as default, the first address automatically becomes the default. | validation: maxItems 50 - name: tag | type: AddressTag | description: Address type classification. Helps categorize the address purpose. Default: `OTHER` - enum: OTHER, HOME, WORK, BILLING, SHIPPING - name: address | type: Address | description: Physical address information including street, city, country, and postal code. Contains structured address data following common address formatting standards. - name: city | type: string | description: none - name: subdivision | type: string | description: none - name: country | type: string | description: none - name: postalCode | type: string | description: none - name: addressLine1 | type: string | description: none - name: addressLine2 | type: string | description: none - name: defaultAddress | type: boolean | description: Whether this address is the contact's default address. Only one address can be designated as default per contact. If no address is explicitly set as default, the first address automatically becomes the default. - name: _id | type: string | description: Address GUID. | validation: format GUID - name: recipient | type: Recipient | description: Address recipient information for delivery purposes. - name: firstName | type: string | description: Recipient's first name. | validation: maxLength 1000 - name: lastName | type: string | description: Recipient's last name. | validation: maxLength 1000 - name: company | type: string | description: Recipient's company name. | validation: maxLength 1000 - name: phone | type: string | description: Recipient's phone number. | validation: minLength 1, maxLength 50 - name: company | type: ContactCompany | description: Contact's company information including company name and job title. - name: name | type: string | description: Contact's company name. | validation: maxLength 1000 - name: jobTitle | type: string | description: Contact's job title. | validation: maxLength 1000 - name: locale | type: string | description: Locale in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. Typically, this is a lowercase 2-letter language code, followed by a hyphen, followed by an uppercase 2-letter country code. For example, `en-US` for U.S. English, and `de-DE` for Germany German. | validation: format LANGUAGE_TAG - name: birthdate | type: string | description: Birth date in `YYYY-MM-DD` format. For example, `2020-03-15`. | validation: format LOCAL_DATE - name: timeZone | type: string | description: IANA time zone identifier for the contact's location. Valid values are IANA time zone GUIDs, such as 'Europe/Rome' or 'America/New_York'. | validation: maxLength 50 - name: assigneeId | type: string | description: Site contributor user GUID assigned to manage communication with this contact. Must be a valid GUGUID referencing an existing site contributor. Only one assignee can be set per contact. | validation: format GUID - name: locationIds | type: array | description: List of business location GUIDs associated with this contact. Used for multi-location businesses to organize contacts by physical business locations. Each GUID must be a valid GUGUID referencing an existing business location. | validation: maxItems 50, format GUID - name: image | type: string | description: Contact's profile image. - name: source | type: ContactSource | description: Details about the origin of the contact. This field is immutable and set automatically when the contact is created. | validation: immutable - name: userId | type: string | description: GUID of the user who created this contact. | validation: format GUID, immutable - name: appId | type: string | description: GUID of the application that created this contact. | validation: format GUID, immutable - name: additionalInfo | type: string | description: Additional information about the contact's origin or creation context. | validation: maxLength 1000, immutable - name: lastActivity | type: ContactActivity | description: Details about the contact's most recent activity on the site. Includes activity date and template GUID. This field is read-only and updated automatically. - name: date | type: Date | description: Date and time when the contact's most recent activity occurred. - name: templateId | type: string | description: GUID of the activity template that defines the type of activity performed. References a template in the contacts activity log system. | validation: format GUID - name: segmentIds | type: array | description: IDs of the segments the contact belongs to. Segments are used for organizing and targeting groups of contacts. | validation: maxItems 60, format GUID - name: memberInfo | type: MemberInfo | description: Contact's site membership information including member GUID, status, and profile details. This field is read-only and populated automatically when the contact is also a site member. Updates are eventually consistent: changes to the underlying member, identity, or profile are reflected after the corresponding events are processed. - name: memberId | type: string | description: Member GUID. | validation: format GUID - name: signupDate | type: Date | description: Date and time the member signed up. - name: email | type: string | description: Email the member uses to log in. | validation: format EMAIL - name: emailVerified | type: boolean | description: Whether the email is verified. - name: emailVerificationRequired | type: boolean | description: Whether the member is required to verify their email before they can log in. - name: status | type: MemberStatus | description: Member status. - `PENDING`: Member created and is waiting for approval by site owner. - `ACTIVE`: Member can log in to the site. - `BLOCKED`: Member is blocked and cannot log in to the site. - `OFFLINE`: Member is a [managed writer](https://support.wix.com/en/article/wix-blog-adding-managed-writers-to-your-blog) for the site blog and cannot log in to the site. - enum: PENDING, ACTIVE, BLOCKED, OFFLINE - name: profileInfo | type: ProfileInfo | description: Information about the member's public profile. - name: nickname | type: string | description: Member's nickname. | validation: maxLength 255 - name: privacyStatus | type: PrivacyStatus | description: Whether the member's profile is visible to other site members and visitors. - enum: PRIVATE, PUBLIC - name: reported | type: boolean | description: Whether the member has been reported by another member. - name: muted | type: boolean | description: Whether the member has been muted and can't post or comment on the site. - name: photo | type: string | description: Member's profile photo. - name: userInfo | type: UserInfo | description: Information about the member's user account. - name: userId | type: string | description: User GUID. | validation: format GUID - name: role | type: Role | description: Member's role on the site. - enum: OWNER, CONTRIBUTOR, MEMBER - name: sessionInfo | type: SessionInfo | description: Information about the member's login sessions. - name: lastWebLogin | type: Date | description: Date and time the member last logged in to the site from a browser. - name: lastMobileLogin | type: Date | description: Date and time the member last logged in from one of the mobile apps. - name: mobileAppNames | type: array | description: Mobile apps the member has ever logged in to. | validation: maxItems 50, maxLength 50 - name: groupInfo | type: GroupInfo | description: Information about the groups the member belongs to. - name: groupIds | type: array | description: IDs of the groups the member belongs to. | validation: maxItems 1000, format GUID - name: tags | type: PrivateTags | description: Tags assigned to the contact for organization and filtering. - name: privateTags | type: TagList | description: Tags that require an additional permission to access, normally not given to site members or visitors. - name: tagIds | type: array | description: A list of tag GUIDs. To create a tag, use the [Tags API](https://dev.wix.com/docs/api-reference/business-management/tags/introduction.md) with the contacts FQDN: `wix.contacts.*.contact`. | validation: maxItems 1000, maxLength 5 - name: extendedFields | type: ExtendedFields | description: Extended fields for storing custom contact data beyond the standard fields. Allows adding custom properties specific to business needs. To define a custom extended field, use the [Schema Service API](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/about-the-data-extension-schema-api.md) with the contacts FQDN: `wix.contacts.*.contact`. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the current page. | validation: format int32 - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. | validation: maxLength 16000 - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. | validation: maxLength 16000 - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. - name: total | type: integer | description: Total number of items matching the filter. Available only on the first page of Search results, not included in Query or List results. If the Search results span multiple pages, the value of `total` can exceed the number of items returned on the first page. | validation: format int32 - name: aggregationData | type: AggregationData | description: Aggregation data. - name: results | type: array | description: Results of the requested aggregations. | validation: maxItems 10000 - ONE-OF: - name: values | type: ValueResults | description: Value aggregation results. - name: results | type: array | description: Value aggregation results. | validation: maxItems 250 - name: value | type: string | description: Value of the field. | validation: maxLength 100 - name: count | type: integer | description: Count of entities with this value. - name: ranges | type: RangeResults | description: Range aggregation results. - name: results | type: array | description: Range results, returned in the same order as requested. | validation: maxItems 50 - name: from | type: number | description: Inclusive lower bound of the range. - name: to | type: number | description: Exclusive upper bound of the range. - name: count | type: integer | description: Count of entities in this range. - name: scalar | type: ScalarResult | description: Scalar aggregation results. - name: type | type: ScalarType | description: Type of scalar aggregation. - enum: - COUNT_DISTINCT: Count of distinct values. - MIN: Minimum value. - MAX: Maximum value. - name: value | type: number | description: Value of the scalar aggregation. - name: dateHistogram | type: DateHistogramResults | description: Date histogram aggregation results. - name: results | type: array | description: Date histogram aggregation results. | validation: maxItems 200 - name: value | type: string | description: Date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. | validation: maxLength 100 - name: count | type: integer | description: Count of documents in the bucket. - name: nested | type: NestedResults | description: Nested aggregation results. - name: results | type: array | description: Nested aggregation results. | validation: maxItems 1000 - name: results | type: Map | description: Nested aggregation results, keyed by aggregation name. | validation: format map - ONE-OF: - name: value | type: ValueResult | description: Value aggregation result. - name: value | type: string | description: Value of the field. | validation: maxLength 1000 - name: count | type: integer | description: Count of entities with this value. | validation: format int32 - name: range | type: RangeResult | description: Range aggregation result. - name: from | type: number | description: Inclusive lower bound of the range. - name: to | type: number | description: Exclusive upper bound of the range. - name: count | type: integer | description: Count of entities in this range. | validation: format int32 - name: scalar | type: ScalarResult | description: Scalar aggregation result. - name: value | type: number | description: Value of the scalar aggregation. - name: dateHistogram | type: ValueResult | description: Date histogram aggregation result. - name: name | type: string | description: User-defined name of the aggregation, as provided in the search request. | validation: maxLength 100 - name: type | type: AggregationType | description: Type of aggregation. Matches the `kind` provided in the search request. - enum: - VALUE: An aggregation where result buckets are dynamically built, one per unique value. - RANGE: An aggregation where you can define a set of ranges, each representing a bucket. - SCALAR: A single-value metric aggregation, such as min, max, sum, or avg. - DATE_HISTOGRAM: An aggregation where result buckets are dynamically built, one per time interval (hour, day, week, and so on). - NESTED: Multi-level aggregation, where each next aggregation is nested within the previous one. - name: fieldPath | type: string | description: Field to aggregate by, as provided in the search request. | validation: maxLength 200 ``` ### Examples ### Search contacts with a text query ```javascript import { contactsV5 } from "@wix/crm"; const search = { search: { expression: "John", mode: "OR", fuzzy: true, }, sort: [{ fieldName: "createdDate", order: "ASC" }], cursorPaging: { limit: 10 }, }; const options = { nameFormat: "BY_FIRST_NAME", }; async function searchContacts() { const response = await contactsV5.searchContacts(search, options); } /* Promise resolves to: * { * "contacts": [ * { * "revision": "2", * "name": { "first": "John", "last": "Doe" }, * "email": { * "email": "john.doe@example.com", * "subscriptionStatus": { "status": "NOT_SET" }, * "deliverabilityStatus": "NOT_SET" * }, * "company": { "name": "Acme Corp", "jobTitle": "Software Engineer" }, * "source": { "appId": "e9022116-5b20-46d1-a29d-fd1b611ca438" }, * "_id": "085ccffa-6686-427f-a310-9b5e3058ebbc" * }, * { * "revision": "3", * "name": { "first": "Robert", "last": "Johnson" }, * "email": { * "email": "bob.johnson@example.com", * "subscriptionStatus": { "status": "NOT_SET" }, * "deliverabilityStatus": "NOT_SET" * }, * "company": { "name": "Johnson Consulting", "jobTitle": "Principal Consultant" }, * "source": { "appId": "e9022116-5b20-46d1-a29d-fd1b611ca438" }, * "_id": "e3f2e525-571b-4274-add8-06034b27c13c" * } * ], * "pagingMetadata": { * "count": 2, * "cursors": {}, * "hasNext": false, * "total": 2 * } * } */ ``` ### searchContacts (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { contactsV5 } from '@wix/crm'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { contactsV5 }, // Include the auth strategy and host as relevant }); async function searchContacts(search,options) { const response = await myWixClient.contactsV5.searchContacts(search,options); }; ``` ---