> 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 # ListParticipants # Package: audiences # Namespace: AudienceService # Method link: https://dev.wix.com/docs/api-reference/business-management/notifications/audiences/audience-v1/list-participants.md ## Permission Scopes: Set Up Automations: SCOPE.CRM.SETUP-AUTOMATIONS ## Introduction Retrieves a list of participants that belong to one or more audiences, an explicit list of participants, or both. Retrieve the available audience providers first by calling [List Audience Providers](https://dev.wix.com/docs/api-reference/business-management/notifications/audiences/participant-v1/list-audience-providers.md). Each audience references a provider's `id`, together with the input data that provider needs to resolve participants. Results are paginated per audience: `ListParticipants` returns participants for a single audience per page before moving on to the next audience in the request. Pass the returned `pagingMetadata.cursors.next` value in the next call's `paging.cursor` to get the next page. Treat the cursor as an opaque value. Include `fields: ["ENRICHED"]` in the request to also return full contact or Wix user data for each participant. --- ## REST API ### Schema ``` Method: listParticipants Description: Retrieves a list of participants that belong to one or more audiences, an explicit list of participants, or both. Retrieve the available audience providers first by calling [List Audience Providers](https://dev.wix.com/docs/api-reference/business-management/notifications/audiences/participant-v1/list-audience-providers.md). Each audience references a provider's `id`, together with the input data that provider needs to resolve participants. Results are paginated per audience: `ListParticipants` returns participants for a single audience per page before moving on to the next audience in the request. Pass the returned `pagingMetadata.cursors.next` value in the next call's `paging.cursor` to get the next page. Treat the cursor as an opaque value. Include `fields: ["ENRICHED"]` in the request to also return full contact or Wix user data for each participant. URL: https://www.wixapis.com/audience-service/v1/participants/list Method: POST Method parameters: param name: audiences | type: array | description: Audiences to retrieve participants from. Each audience specifies a provider, identified by `audienceProviderId`, and the input data that provider needs to resolve participants. | validation: maxItems 20 - name: audienceProviderId | type: string | description: identifier of the provider | validation: minLength 1, maxLength 100 - name: audienceProviderData | type: object | description: audience provider data is needed in order to list participants of each provider param name: fields | type: array | description: Specifies which additional fields to return for each participant. Currently supports a single value. | validation: maxItems 1 - enum: - ENRICHED: Returns the full connected entity, either Wix user or contact data, for each participant. param name: locationIds | type: array | description: Location GUIDs used to filter for participants relevant to these locations. | validation: maxItems 30, format GUID param name: paging | type: CursorPaging - 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 param name: participants | type: array | description: Explicit participants to include in addition to those resolved from `audiences`. These participants are merged into the same result set and are subject to the same enrichment and filtering logic as participants resolved from `audiences`. | validation: maxItems 25 - ONE-OF: - name: wixUserIdentifier | type: WixUserParticipant | description: Identifier of a Wix user (site owner, contributor, etc.). - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). | validation: format GUID - name: accountId | type: string | description: GUID of the account should be exist unless the provider audience return wix-user that its account context is not relevant | validation: format GUID - name: contactIdentifier | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: anonymousIdentifier | type: AnonymousParticipant | description: Information about an anonymous participant, identified by an email address or phone number, or both. - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - name: contactParticipantIdentifier | type: ContactParticipant | description: Identifier of a contact participant. - name: contactId | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - name: type | type: ParticipantType | description: Type of the participant. - enum: WIX_USER, CONTACT, ANONYMOUS Return type: ListParticipantsResponse - name: participants | type: array | description: Participants that are part of the requested audiences. Each participant is returned only once, even if it matches more than one audience. - ONE-OF: - name: wixUserIdentifier | type: WixUserParticipant | description: Identifier of a Wix user (site owner, contributor, etc.). - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). | validation: format GUID - name: accountId | type: string | description: GUID of the account should be exist unless the provider audience return wix-user that its account context is not relevant | validation: format GUID - name: contactIdentifier | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: anonymousIdentifier | type: AnonymousParticipant | description: Information about an anonymous participant, identified by an email address or phone number, or both. - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - name: contactParticipantIdentifier | type: ContactParticipant | description: Identifier of a contact participant. - name: contactId | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - ONE-OF: - name: wixUserData | type: WixUser | description: Full Wix user data for the participant. Returned only when `fields` includes `ENRICHED` and the participant's `type` is `WIX_USER`. | read-only: true - name: id | type: string | description: User GUID. | read-only: true | validation: format GUID - name: accountId | type: string | description: Account GUID. | read-only: true | validation: format GUID - name: firstName | type: string | description: User's first name. | read-only: true | validation: minLength 1, maxLength 50 - name: lastName | type: string | description: User's last name. | read-only: true | validation: minLength 1, maxLength 50 - name: email | type: string | description: User's email address. | read-only: true | validation: format EMAIL - name: phone | type: string | description: User's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. | read-only: true | validation: format PHONE - name: language | type: string | description: User's locale, in IETF BCP 47 language tag format. For example, `en-US` for U.S. English. | read-only: true | validation: format LANGUAGE_TAG - name: contactData | type: Contact | description: Full contact data for the participant. Returned only when `fields` includes `ENRICHED` and the participant's `type` is `CONTACT`. | read-only: true - name: id | type: string | description: Contact GUID. | read-only: true | validation: format GUID - name: revision | type: integer | description: Revision number, which increments by 1 each time the contact is updated. To prevent conflicting changes, the existing `revision` must be specified when updating a contact. | read-only: true - name: source | type: ContactSource | description: Details about the contact's source. | read-only: true - name: sourceType | type: ContactSourceType | description: Source type. | read-only: true - enum: OTHER, ADMIN, WIX_APP, IMPORT, THIRD_PARTY, WIX_BOOKINGS, WIX_CHAT, WIX_EMAIL_MARKETING, WIX_EVENTS, WIX_FORMS, WIX_GROUPS, WIX_HOTELS, WIX_MARKET_PLACE, WIX_MUSIC, WIX_RESTAURANTS, WIX_SITE_MEMBERS, WIX_STORES, WIX_CODE, HOPP - name: appId | type: string | description: App GUID, if the contact was created by an app. | read-only: true | validation: format GUID - name: createdDate | type: string | description: Date and time the contact was created. | read-only: true | validation: format date-time - name: updatedDate | type: string | description: Date and time the contact was last updated. | read-only: true | validation: format date-time - name: lastActivity | type: ContactActivity | description: Details about the contact's last action in the site. | read-only: true - name: activityDate | type: string | description: Date and time of the last action. | validation: format date-time - name: activityType | type: ContactActivityType | description: Contact's last action in the site. - enum: - GENERAL: Visited the site. - CONTACT_CREATED: Became a new contact. - MEMBER_LOGIN: Logged in. - MEMBER_REGISTER: Requested a 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 the site. - INBOX_MESSAGE_FROM_CUSTOMER: Sent a new message to the site. - NEWSLETTER_SUBSCRIPTION_FORM_SUBMITTED: Subscribed to a site newsletter through a form. - NEWSLETTER_SUBSCRIPTION_UNSUBSCRIBE: Unsubscribed from a site newsletter. - ECOM_PURCHASE: Made a purchase. - ECOM_CART_ABANDON: Abandoned a shopping cart. - ECOM_CHECKOUT_BUYER: Checked out shopping cart and submitted buyer info (but didn’t complete the 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: RSVP'd to an event. - INVOICE_PAY: Paid an invoice. - INVOICE_OVERDUE: An invoice is now overdue. - PRICE_QUOTE_ACCEPT: Accepted a price quote. - PRICE_QUOTE_EXPIRE: A 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. - NEWSLETTER_SUBSCRIPTION_SUBSCRIBE: Subscribed to a site newsletter. - NEWSLETTER_SUBSCRIPTION_PENDING: Subscription status to site newsletters is pending confirmation. - NEWSLETTER_SUBSCRIPTION_NOT_SET: Subscription status to site newsletters is not set. - PHONE_SUBSCRIPTION_SUBSCRIBE: Subscribed to phone notifications. - PHONE_SUBSCRIPTION_PENDING: Subscription to phone notificatons is pending confirmation. - PHONE_SUBSCRIPTION_NOT_SET: Subscription to phone notificatons is not set. - PHONE_SUBSCRIPTION_UNSUBSCRIBE: Subscribed to phone notifications. - name: primaryInfo | type: PrimaryContactInfo | description: Contact's primary phone and email. | read-only: true - name: email | type: string | description: Primary email address. This property reflects the email address in `info.emails` where `primary` is `true`. | read-only: true | validation: format EMAIL - name: phone | type: string | description: Primary phone number. This property reflects the phone number in `info.phones` where `primary` is `true`. | read-only: true - name: info | type: ContactInfo | description: Contact's details. - name: name | type: ContactName | description: Contact's 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: emails | type: ContactEmailsWrapper | description: Contact's email addresses. - name: items | type: array | description: List of up to 50 email addresses. | validation: maxItems 50 - name: id | type: string | description: Email GUID. | read-only: true | validation: format GUID - name: tag | type: EmailTag | description: Email type. `UNTAGGED` is shown as "Other" in the Contact List. - enum: UNTAGGED, MAIN, HOME, WORK - name: email | type: string | description: Email address. | validation: minLength 1, maxLength 320 - name: primary | type: boolean | description: Indicates whether this is the contact's primary email address. When changing `primary` to `true` for an email, the contact's other emails become `false`. Changing the primary email of a contact also affects the subscription status to marketing emails that are decided based on the primary email. - name: phones | type: ContactPhonesWrapper | description: Contact's phone numbers. - name: items | type: array | description: List of up to 50 phone numbers. | validation: maxItems 50 - name: id | type: string | description: Phone GUID. | read-only: true | validation: format GUID - name: tag | type: PhoneTag | description: Phone type. `UNTAGGED` is shown as "Other" in the Contact List. - enum: UNTAGGED, MAIN, HOME, MOBILE, WORK, FAX - name: countryCode | type: string | description: [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. | validation: format COUNTRY - name: phone | type: string | description: Phone number. | validation: minLength 1, maxLength 50 - name: e164Phone | type: string | description: [ITU E.164-formatted](https://www.itu.int/rec/T-REC-E.164/) phone number. Automatically generated using `phone` and `countryCode`, pending both values are valid. | read-only: true - name: primary | type: boolean | description: Indicates whether this is the contact's primary phone number. When changing `primary` to `true` for a phone, the contact's `primary` field for other phones becomes `false`. Changing the primary phone number also affects the subscription status to SMS messages that are decided based on the primary phone. - name: addresses | type: ContactAddressesWrapper | description: Contact's street addresses. - name: items | type: array | description: List of up to 50 addresses. | validation: maxItems 50 - name: id | type: string | description: Street address GUID. | read-only: true | validation: format GUID - name: tag | type: AddressTag | description: Address type. `UNTAGGED` is shown as "Other" in the Contact List. - enum: UNTAGGED, HOME, WORK, BILLING, SHIPPING - name: address | type: Address | description: Street address. - 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 1000 - 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: Code for a subdivision (such as state, prefecture, or province) in an [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. | validation: maxLength 100 - name: city | type: string | description: City name. | validation: maxLength 1000 - 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: company | type: string | description: Contact's company name. | validation: maxLength 1000 - name: jobTitle | type: string | description: Contact's job title. | validation: maxLength 1000 - name: birthdate | type: string | description: Birth date in `YYYY-MM-DD` format. For example, `2020-03-15`. | validation: format LOCAL_DATE - 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: labelKeys | type: LabelsWrapper | description: List of contact's labels. Labels are used to organize contacts. Labels can be added and removed using Label Contact and Unlabel Contact, respectively. To view or manage contact labels, use the Labels API. - name: items | type: array | description: List of contact label keys. Contact labels help categorize contacts. Label keys must exist to be added to the contact. Contact labels can be created or retrieved with Find or Create Label or List Labels. | validation: maxItems 2000 - name: extendedFields | type: ExtendedFieldsWrapper | description: Additional custom fields. Empty fields are not returned. - name: items | type: Map | description: Contact's extended fields, where each key is the field key, and each value is the field's value for the contact. To view and manage extended fields, use the Extended Fields API. | validation: format map - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: picture | type: ContactPicture | description: Contact's profile picture. - name: image | type: Image | description: Image. This can contain an image URL or a Wix Media image GUID. - name: id | type: string | description: WixMedia image GUID. This property is written by Wix when an image is uploaded to the Wix Media Manager. - name: url | type: string | description: Image source: Either a Media Manager URL or external URL. - name: height | type: integer | description: Height of the original image. - name: width | type: integer | description: Width of the original image. - name: altText | type: string | description: Image alt text (optional). - name: urlExpirationDate | type: string | description: Image URL expiration date (optional). | read-only: true | validation: format date-time - name: primaryEmail | type: PrimaryEmail | description: Contact's primary email details. | read-only: true - name: email | type: string | description: Primary email address. This field reflects the email address in `info.emails` where `primary` is `true`. | read-only: true | validation: format EMAIL - name: subscriptionStatus | type: SubscriptionStatus | description: Indicates the recipient's opt-in or opt-out status for marketing emails. Default: `NOT_SET` | read-only: true - enum: - NO_SUBSCRIPTION_STATUS: No status exists. - NOT_SET: No status specified. - PENDING: Subscription confirmation was requested, but recipient hasn't confirmed yet. - SUBSCRIBED: Recipient has opted in to marketing emails or SMS messages. - UNSUBSCRIBED: Recipient has opted out of marketing emails or SMS messages. - name: deliverabilityStatus | type: EmailDeliverabilityStatus | description: Indicates last reported status of sent emails. Default: `NOT_SET` | read-only: true - enum: - NOT_SET: No status reported. - VALID: Emails are being successfully delivered. - BOUNCED: The last email to the recipient bounced or was rejected. - SPAM_COMPLAINT: Recipient registered a spam complaint with their email provider. - INACTIVE: Multiple emails have been delivered without any kind of engagement from the recipient. - name: primaryPhone | type: PrimaryPhone | description: Contact's primary phone details. | read-only: true - name: countryCode | type: string | description: Country code of the primary phone number in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. | validation: format COUNTRY - name: e164Phone | type: string | description: Phone number in [ITU E.164](https://www.itu.int/rec/T-REC-E.164/) format. Automatically generated using `phone` and `countryCode` when both values are valid. | read-only: true - name: formattedPhone | type: string | description: Formatted phone. Automatically generated using `phone` and `countryCode`. | read-only: true - name: subscriptionStatus | type: SubscriptionStatus | description: Indicates the recipient's opt-in or opt-out status for SMS messages. Default: - `NOT_SET` when the phone is a valid E164 phone. - `NO_SUBSCRIPTION_STATUS` when the phone is not a valid E164 phone. | read-only: true - name: phone | type: string | description: Primary phone number. This field reflects the phone number in `info.phones` where `primary` is `true`. | read-only: true - name: id | type: string | description: Participant GUID. Not populated, since participants are resolved on demand from audience providers and aren't independently addressable by GUID. | read-only: true | validation: format GUID - name: type | type: ParticipantType | description: Type of the participant. - enum: WIX_USER, CONTACT, ANONYMOUS - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. | 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. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_PROVIDER_ID | Description: The audience's `audienceProviderId` isn't in the expected `{appId}_{key}` format. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_CURSOR | Description: The provided `cursor` is invalid. ``` ### Examples ### List the contacts labeled VIP Customer Resolves an audience of contacts with the `custom.vip-customer` label, returning full contact data for each participant. ```curl curl -X POST \ 'https://www.wixapis.com/audience-service/v1/participants/list' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "audiences": [ { "audienceProviderId": "74bff718-5977-47f2-9e5f-a9fd0047fd1f_labels", "audienceProviderData": { "labelIds": ["custom.vip-customer"] } } ], "fields": ["ENRICHED"], "paging": { "limit": 2 } }' ``` ### Combine an audience with an explicit participant Resolves a contact-by-ID audience together with an explicit participant in the same request. Explicit participants are always returned on the first page; audiences are resolved starting from the next page. ```curl curl -X POST \ 'https://www.wixapis.com/audience-service/v1/participants/list' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "audiences": [ { "audienceProviderId": "74bff718-5977-47f2-9e5f-a9fd0047fd1f_contacts", "audienceProviderData": { "ids": ["21c181ef-30bf-4b06-8a1f-d7e3a844bdd1"] } } ], "participants": [ { "type": "CONTACT", "contactParticipantIdentifier": { "contactId": "ac0d065a-0f61-4281-a60f-c1ea669bb33b" } } ], "fields": ["ENRICHED"] }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.audiences.audiences.listParticipants(options) Description: Retrieves a list of participants that belong to one or more audiences, an explicit list of participants, or both. Retrieve the available audience providers first by calling [List Audience Providers](https://dev.wix.com/docs/api-reference/business-management/notifications/audiences/participant-v1/list-audience-providers.md). Each audience references a provider's `id`, together with the input data that provider needs to resolve participants. Results are paginated per audience: `ListParticipants` returns participants for a single audience per page before moving on to the next audience in the request. Pass the returned `pagingMetadata.cursors.next` value in the next call's `paging.cursor` to get the next page. Treat the cursor as an opaque value. Include `fields: ["ENRICHED"]` in the request to also return full contact or Wix user data for each participant. Method parameters: param name: options | type: ListParticipantsOptions none - name: audiences | type: array | description: Audiences to retrieve participants from. Each audience specifies a provider, identified by `audienceProviderId`, and the input data that provider needs to resolve participants. | validation: maxItems 20 - name: audienceProviderId | type: string | description: identifier of the provider | validation: minLength 1, maxLength 100 - name: audienceProviderData | type: object | description: audience provider data is needed in order to list participants of each provider - name: participants | type: array | description: Explicit participants to include in addition to those resolved from `audiences`. These participants are merged into the same result set and are subject to the same enrichment and filtering logic as participants resolved from `audiences`. | validation: maxItems 25 - ONE-OF: - name: wixUserIdentifier | type: WixUserParticipant | description: Identifier of a Wix user (site owner, contributor, etc.). - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). | validation: format GUID - name: accountId | type: string | description: GUID of the account should be exist unless the provider audience return wix-user that its account context is not relevant | validation: format GUID - name: contactIdentifier | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: anonymousIdentifier | type: AnonymousParticipant | description: Information about an anonymous participant, identified by an email address or phone number, or both. - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - name: contactParticipantIdentifier | type: ContactParticipant | description: Identifier of a contact participant. - name: contactId | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - name: type | type: ParticipantType | description: Type of the participant. - enum: WIX_USER, CONTACT, ANONYMOUS - name: paging | type: CursorPaging | description: Cursor paging options. - 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: fields | type: array | description: Specifies which additional fields to return for each participant. Currently supports a single value. | validation: maxItems 1 - enum: - ENRICHED: Returns the full connected entity, either Wix user or contact data, for each participant. - name: locationIds | type: array | description: Location GUIDs used to filter for participants relevant to these locations. | validation: maxItems 30, format GUID Return type: PROMISE - name: participants | type: array | description: Participants that are part of the requested audiences. Each participant is returned only once, even if it matches more than one audience. - ONE-OF: - name: wixUserIdentifier | type: WixUserParticipant | description: Identifier of a Wix user (site owner, contributor, etc.). - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). | validation: format GUID - name: accountId | type: string | description: GUID of the account should be exist unless the provider audience return wix-user that its account context is not relevant | validation: format GUID - name: contactIdentifier | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: anonymousIdentifier | type: AnonymousParticipant | description: Information about an anonymous participant, identified by an email address or phone number, or both. - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - name: contactParticipantIdentifier | type: ContactParticipant | description: Identifier of a contact participant. - name: contactId | type: string | description: GUID of a [contact](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md) in the site. | validation: format GUID - name: email | type: string | description: Participant email address | validation: format EMAIL - name: phone | type: string | description: Participant phone number in [E.164](https://en.wikipedia.org/wiki/E.164) | validation: format PHONE - ONE-OF: - name: wixUserData | type: WixUser | description: Full Wix user data for the participant. Returned only when `fields` includes `ENRICHED` and the participant's `type` is `WIX_USER`. | read-only: true - name: _id | type: string | description: User GUID. | read-only: true | validation: format GUID - name: accountId | type: string | description: Account GUID. | read-only: true | validation: format GUID - name: firstName | type: string | description: User's first name. | read-only: true | validation: minLength 1, maxLength 50 - name: lastName | type: string | description: User's last name. | read-only: true | validation: minLength 1, maxLength 50 - name: email | type: string | description: User's email address. | read-only: true | validation: format EMAIL - name: phone | type: string | description: User's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. | read-only: true | validation: format PHONE - name: language | type: string | description: User's locale, in IETF BCP 47 language tag format. For example, `en-US` for U.S. English. | read-only: true | validation: format LANGUAGE_TAG - name: contactData | type: Contact | description: Full contact data for the participant. Returned only when `fields` includes `ENRICHED` and the participant's `type` is `CONTACT`. | read-only: true - name: _id | type: string | description: Contact GUID. | read-only: true | validation: format GUID - name: revision | type: integer | description: Revision number, which increments by 1 each time the contact is updated. To prevent conflicting changes, the existing `revision` must be specified when updating a contact. | read-only: true - name: source | type: ContactSource | description: Details about the contact's source. | read-only: true - name: sourceType | type: ContactSourceType | description: Source type. | read-only: true - enum: OTHER, ADMIN, WIX_APP, IMPORT, THIRD_PARTY, WIX_BOOKINGS, WIX_CHAT, WIX_EMAIL_MARKETING, WIX_EVENTS, WIX_FORMS, WIX_GROUPS, WIX_HOTELS, WIX_MARKET_PLACE, WIX_MUSIC, WIX_RESTAURANTS, WIX_SITE_MEMBERS, WIX_STORES, WIX_CODE, HOPP - name: appId | type: string | description: App GUID, if the contact was created by an app. | read-only: true | validation: format GUID - name: _createdDate | type: Date | description: Date and time the contact was created. | read-only: true - name: _updatedDate | type: Date | description: Date and time the contact was last updated. | read-only: true - name: lastActivity | type: ContactActivity | description: Details about the contact's last action in the site. | read-only: true - name: activityDate | type: Date | description: Date and time of the last action. - name: activityType | type: ContactActivityType | description: Contact's last action in the site. - enum: - GENERAL: Visited the site. - CONTACT_CREATED: Became a new contact. - MEMBER_LOGIN: Logged in. - MEMBER_REGISTER: Requested a 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 the site. - INBOX_MESSAGE_FROM_CUSTOMER: Sent a new message to the site. - NEWSLETTER_SUBSCRIPTION_FORM_SUBMITTED: Subscribed to a site newsletter through a form. - NEWSLETTER_SUBSCRIPTION_UNSUBSCRIBE: Unsubscribed from a site newsletter. - ECOM_PURCHASE: Made a purchase. - ECOM_CART_ABANDON: Abandoned a shopping cart. - ECOM_CHECKOUT_BUYER: Checked out shopping cart and submitted buyer info (but didn’t complete the 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: RSVP'd to an event. - INVOICE_PAY: Paid an invoice. - INVOICE_OVERDUE: An invoice is now overdue. - PRICE_QUOTE_ACCEPT: Accepted a price quote. - PRICE_QUOTE_EXPIRE: A 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. - NEWSLETTER_SUBSCRIPTION_SUBSCRIBE: Subscribed to a site newsletter. - NEWSLETTER_SUBSCRIPTION_PENDING: Subscription status to site newsletters is pending confirmation. - NEWSLETTER_SUBSCRIPTION_NOT_SET: Subscription status to site newsletters is not set. - PHONE_SUBSCRIPTION_SUBSCRIBE: Subscribed to phone notifications. - PHONE_SUBSCRIPTION_PENDING: Subscription to phone notificatons is pending confirmation. - PHONE_SUBSCRIPTION_NOT_SET: Subscription to phone notificatons is not set. - PHONE_SUBSCRIPTION_UNSUBSCRIBE: Subscribed to phone notifications. - name: primaryInfo | type: PrimaryContactInfo | description: Contact's primary phone and email. | read-only: true - name: email | type: string | description: Primary email address. This property reflects the email address in `info.emails` where `primary` is `true`. | read-only: true | validation: format EMAIL - name: phone | type: string | description: Primary phone number. This property reflects the phone number in `info.phones` where `primary` is `true`. | read-only: true - name: info | type: ContactInfo | description: Contact's details. - name: name | type: ContactName | description: Contact's 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: emails | type: ContactEmailsWrapper | description: Contact's email addresses. - name: items | type: array | description: List of up to 50 email addresses. | validation: maxItems 50 - name: _id | type: string | description: Email GUID. | read-only: true | validation: format GUID - name: tag | type: EmailTag | description: Email type. `UNTAGGED` is shown as "Other" in the Contact List. - enum: UNTAGGED, MAIN, HOME, WORK - name: email | type: string | description: Email address. | validation: minLength 1, maxLength 320 - name: primary | type: boolean | description: Indicates whether this is the contact's primary email address. When changing `primary` to `true` for an email, the contact's other emails become `false`. Changing the primary email of a contact also affects the subscription status to marketing emails that are decided based on the primary email. - name: phones | type: ContactPhonesWrapper | description: Contact's phone numbers. - name: items | type: array | description: List of up to 50 phone numbers. | validation: maxItems 50 - name: _id | type: string | description: Phone GUID. | read-only: true | validation: format GUID - name: tag | type: PhoneTag | description: Phone type. `UNTAGGED` is shown as "Other" in the Contact List. - enum: UNTAGGED, MAIN, HOME, MOBILE, WORK, FAX - name: countryCode | type: string | description: [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. | validation: format COUNTRY - name: phone | type: string | description: Phone number. | validation: minLength 1, maxLength 50 - name: e164Phone | type: string | description: [ITU E.164-formatted](https://www.itu.int/rec/T-REC-E.164/) phone number. Automatically generated using `phone` and `countryCode`, pending both values are valid. | read-only: true - name: primary | type: boolean | description: Indicates whether this is the contact's primary phone number. When changing `primary` to `true` for a phone, the contact's `primary` field for other phones becomes `false`. Changing the primary phone number also affects the subscription status to SMS messages that are decided based on the primary phone. - name: addresses | type: ContactAddressesWrapper | description: Contact's street addresses. - name: items | type: array | description: List of up to 50 addresses. | validation: maxItems 50 - name: _id | type: string | description: Street address GUID. | read-only: true | validation: format GUID - name: tag | type: AddressTag | description: Address type. `UNTAGGED` is shown as "Other" in the Contact List. - enum: UNTAGGED, HOME, WORK, BILLING, SHIPPING - name: address | type: Address | description: Street address. - 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: company | type: string | description: Contact's company name. | validation: maxLength 1000 - name: jobTitle | type: string | description: Contact's job title. | validation: maxLength 1000 - name: birthdate | type: string | description: Birth date in `YYYY-MM-DD` format. For example, `2020-03-15`. | validation: format LOCAL_DATE - 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: labelKeys | type: LabelsWrapper | description: List of contact's labels. Labels are used to organize contacts. Labels can be added and removed using Label Contact and Unlabel Contact, respectively. To view or manage contact labels, use the Labels API. - name: items | type: array | description: List of contact label keys. Contact labels help categorize contacts. Label keys must exist to be added to the contact. Contact labels can be created or retrieved with Find or Create Label or List Labels. | validation: maxItems 2000 - name: extendedFields | type: ExtendedFieldsWrapper | description: Additional custom fields. Empty fields are not returned. - name: items | type: Map | description: Contact's extended fields, where each key is the field key, and each value is the field's value for the contact. To view and manage extended fields, use the Extended Fields API. | validation: format map - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: picture | type: ContactPicture | description: Contact's profile picture. - name: image | type: string | description: Image. This can contain an image URL or a Wix Media image GUID. - name: primaryEmail | type: PrimaryEmail | description: Contact's primary email details. | read-only: true - name: email | type: string | description: Primary email address. This field reflects the email address in `info.emails` where `primary` is `true`. | read-only: true | validation: format EMAIL - name: subscriptionStatus | type: SubscriptionStatus | description: Indicates the recipient's opt-in or opt-out status for marketing emails. Default: `NOT_SET` | read-only: true - enum: - NO_SUBSCRIPTION_STATUS: No status exists. - NOT_SET: No status specified. - PENDING: Subscription confirmation was requested, but recipient hasn't confirmed yet. - SUBSCRIBED: Recipient has opted in to marketing emails or SMS messages. - UNSUBSCRIBED: Recipient has opted out of marketing emails or SMS messages. - name: deliverabilityStatus | type: EmailDeliverabilityStatus | description: Indicates last reported status of sent emails. Default: `NOT_SET` | read-only: true - enum: - NOT_SET: No status reported. - VALID: Emails are being successfully delivered. - BOUNCED: The last email to the recipient bounced or was rejected. - SPAM_COMPLAINT: Recipient registered a spam complaint with their email provider. - INACTIVE: Multiple emails have been delivered without any kind of engagement from the recipient. - name: primaryPhone | type: PrimaryPhone | description: Contact's primary phone details. | read-only: true - name: countryCode | type: string | description: Country code of the primary phone number in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. | validation: format COUNTRY - name: e164Phone | type: string | description: Phone number in [ITU E.164](https://www.itu.int/rec/T-REC-E.164/) format. Automatically generated using `phone` and `countryCode` when both values are valid. | read-only: true - name: formattedPhone | type: string | description: Formatted phone. Automatically generated using `phone` and `countryCode`. | read-only: true - name: subscriptionStatus | type: SubscriptionStatus | description: Indicates the recipient's opt-in or opt-out status for SMS messages. Default: - `NOT_SET` when the phone is a valid E164 phone. - `NO_SUBSCRIPTION_STATUS` when the phone is not a valid E164 phone. | read-only: true - name: phone | type: string | description: Primary phone number. This field reflects the phone number in `info.phones` where `primary` is `true`. | read-only: true - name: _id | type: string | description: Participant GUID. Not populated, since participants are resolved on demand from audience providers and aren't independently addressable by GUID. | read-only: true | validation: format GUID - name: type | type: ParticipantType | description: Type of the participant. - enum: WIX_USER, CONTACT, ANONYMOUS - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. | 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. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_PROVIDER_ID | Description: The audience's `audienceProviderId` isn't in the expected `{appId}_{key}` format. HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_CURSOR | Description: The provided `cursor` is invalid. ``` ### Examples ### Combine an audience with an explicit participant Resolves a contact-by-ID audience together with an explicit participant in the same request. Explicit participants are always returned on the first page; audiences are resolved starting from the next page. ```javascript import { audiences } from "@wix/audiences"; async function listParticipants() { const response = await audiences.listParticipants({ audiences: [ { audienceProviderId: "74bff718-5977-47f2-9e5f-a9fd0047fd1f_contacts", audienceProviderData: { ids: ["21c181ef-30bf-4b06-8a1f-d7e3a844bdd1"], }, }, ], participants: [ { type: "CONTACT", contactParticipantIdentifier: { contactId: "ac0d065a-0f61-4281-a60f-c1ea669bb33b", }, }, ], fields: ["ENRICHED"], }); } /* Promise resolves to: * { * "participants": [ * { * "type": "CONTACT", * "contactParticipantIdentifier": { * "contactId": "ac0d065a-0f61-4281-a60f-c1ea669bb33b" * }, * "contactData": { * "_id": "ac0d065a-0f61-4281-a60f-c1ea669bb33b", * "revision": 1, * "info": { * "name": { * "first": "John", * "last": "Doe" * } * }, * "primaryEmail": { * "email": "john.doe@example.com" * } * } * } * ], * "pagingMetadata": { * "count": 1, * "cursors": { * "next": "eyJhdWRpZW5jZUNvbmZpZ3VyYXRpb24iOnsiaWQiOiI3NGJmZjcxOC01OTc3LTQ3ZjItOWU1Zi1hOWZkMDA0N2ZkMWZfY29udGFjdHMiLCJkYXRhIjp7ImlkcyI6WyIyMWMxODFlZi0zMGJmLTRiMDYtOGExZi1kN2UzYTg0NGJkZDEiXX19LCJhdWRpZW5jZUN1cnNvciI6bnVsbCwibmV4dEF1ZGllbmNlQ29uZmlndXJhdGlvbnMiOltdfQ==" * }, * "hasNext": true * } * } */ ``` ### List the contacts labeled VIP Customer Resolves an audience of contacts with the `custom.vip-customer` label, returning full contact data for each participant. ```javascript import { audiences } from "@wix/audiences"; async function listParticipants() { const response = await audiences.listParticipants({ audiences: [ { audienceProviderId: "74bff718-5977-47f2-9e5f-a9fd0047fd1f_labels", audienceProviderData: { labelIds: ["custom.vip-customer"], }, }, ], fields: ["ENRICHED"], paging: { limit: 2, }, }); } /* Promise resolves to: * { * "participants": [ * { * "type": "CONTACT", * "contactIdentifier": "21c181ef-30bf-4b06-8a1f-d7e3a844bdd1", * "contactData": { * "_id": "21c181ef-30bf-4b06-8a1f-d7e3a844bdd1", * "revision": 3, * "info": { * "name": { * "first": "Adam", * "last": "Friedmann" * } * }, * "primaryEmail": { * "email": "adamfri@wix.com" * } * } * } * ], * "pagingMetadata": { * "count": 1, * "cursors": {}, * "hasNext": false * } * } */ ``` ### listParticipants (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 { audiences } from '@wix/audiences'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { audiences }, // Include the auth strategy and host as relevant }); async function listParticipants(options) { const response = await myWixClient.audiences.listParticipants(options); }; ``` ---