Labels

Labels allow site contributors to segment contacts in their Contact List. Contact labels are useful for targeting specific audiences for email campaigns or bulk actions.

With the label APIs, your app can view and manage a site's labels. The responses can be used to query contacts in subsequent API requests.

For more information on how labels are used, see these Wix Help Center articles:

Was this helpful?
Yes
No

Contact Labels: Supported Filters and Sorting

The following table shows field support for filters and sorting for the label object:

FieldSupported FiltersSortable
key$eq, $ne, $in
displayName$eq, $ne, $in, $startsWithSortable
createdDate$eq, $ne, $gt, $lt, $gte, $lteSortable
updatedDate$eq, $ne, $gt, $lt, $gte, $lteSortable
namespace$eq, $ne
labelType$eq

Related content: API Query Language, Query Labels

Was this helpful?
Yes
No

Label Object

Attributes
namespacestringRead-onlyminLength 1maxLength 25
Label namespace. Labels created by site contributors or 3rd-party apps are automatically assigned to the custom namespace.

namespaceDisplayNamestringRead-onlyminLength 1maxLength 180
Display name for the namespace, used to organize the list of labels in the site Dashboard.

keystringRead-onlyminLength 1maxLength 80
Label key. key is generated when the label is created and cannot be modified, even if displayName changes.

displayNamestringminLength 1maxLength 180
Label display name shown in the Dashboard.

labelTypestringRead-only
4 enum supported values:
UNKNOWNSYSTEMUSER_DEFINEDWIX_APP_DEFINED
Label type.
  • SYSTEM: The label is a default system label for the Contact List.
  • USER_DEFINED: The label was created by a site contributor or 3rd-party app.
  • WIX_APP_DEFINED: The label was created by a Wix app.

createdDatestringRead-onlyformat date-time
Date and time the label was created.

updatedDatestringRead-onlyformat date-time
Date and time the label was last updated.
Was this helpful?
Yes
No

GetList Labels

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Lists all contact labels for a site.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contact Labels
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/contacts/v4/labels

Was this helpful?
Yes
No

PostFind Or Create Label

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a label with a given name, or creates one if it doesn't exist.

Successful calls to this endpoint always return a label, which can be passed to subsequent requests.

For example, in the Contacts API, Label Contact and Unlabel Contact requests will fail if you include a nonexistant label. To ensure successful calls, you can call this endpoint first, and then use the response in the label and unlabel requests.

To find an existing label without potentially creating a new one, use Get Label or List Labels.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contact Labels
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/labels

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

GetGet Label

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a label.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contact Labels
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/contacts/v4/labels/{key}

Was this helpful?
Yes
No

DeleteDelete Label

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes a label from the site and removes it from contacts it applies to.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contact Labels
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/contacts/v4/labels/{key}

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

PatchUpdate Label

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates a label's specified properties.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contact Labels
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/contacts/v4/labels/{label.key}

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

PostQuery Labels

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of contact labels. Up to 1000 labels can be returned per request.

For a detailed list of supported operations, see sorting and filtering for labels. To learn how to query labels, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Contact Labels
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/contacts/v4/labels/query

Was this helpful?
Yes
No

Contact Label Created

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

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

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

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

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

Contact Label Updated

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

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

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

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

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Contact Label Deleted

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

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

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

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

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No