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?
The following table shows field support for filters and sorting for the label object:
| Field | Supported Filters | Sortable |
|---|---|---|
key | $eq, $ne, $in | |
displayName | $eq, $ne, $in, $startsWith | Sortable |
createdDate | $eq, $ne, $gt, $lt, $gte, $lte | Sortable |
updatedDate | $eq, $ne, $gt, $lt, $gte, $lte | Sortable |
namespace | $eq, $ne | |
labelType | $eq |
Related content: API Query Language, Query Labels
Was this helpful?
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 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?
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.Authorization header required - pass the OAuth Access Token
Syntax
GET
https://www.wixapis.com/contacts/v4/labelsWas this helpful?
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.Authorization header required - pass the OAuth Access Token
Syntax
POST
https://www.wixapis.com/contacts/v4/labelsWas this helpful?
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.Authorization header required - pass the OAuth Access Token
Syntax
GET
https://www.wixapis.com/contacts/v4/labels/{key}Was this helpful?
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.Authorization header required - pass the OAuth Access Token
Syntax
DELETE
https://www.wixapis.com/contacts/v4/labels/{key}Was this helpful?
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.Authorization header required - pass the OAuth Access Token
Syntax
PATCH
https://www.wixapis.com/contacts/v4/labels/{label.key}Was this helpful?
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.Authorization header required - pass the OAuth Access Token
Syntax
POST
https://www.wixapis.com/contacts/v4/labels/queryWas this helpful?
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 Body
Event Body Event data is received as a JSON Web Token (JWT). It may be delayed.
Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID.
Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.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?
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 Body
Event Body Event data is received as a JSON Web Token (JWT). It may be delayed.
Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID.
Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.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?
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 Body
Event Body Event data is received as a JSON Web Token (JWT). It may be delayed.
Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID.
Allows clients to ignore duplicate webhooks.
entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.contacts.v4.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?