About the Labels API

The Labels API provides functionality for managing contact labels on a site. Labels allow Wix users to segment or categorize contacts, customizing their contacts organization according to their needs. For example, they can use labels to target specific audiences for email campaigns or bulk actions.

With the Labels API, you can:

  • Create, manage, and delete labels.
  • Retrieve information about existing labels.

Learn more about Creating and Using Contact Labels.

Before you begin

It's important to note the following points before you begin to code:

  • When you delete a label from a site, you also remove that label from all contacts it applies to.
  • Label keys can't be changed once created.

Terminology

  • Label: A tag that is applied to contacts to help Wix users organize and group contacts with shared characteristics. Labels can be either user-defined or system-defined.
    • User-defined label: A label that is custom created by calling the Find Or Create Label method.
    • System-defined label: A label that is pre-defined in a site and can't be deleted from the CRM.
Did this help?

Label Object


Label that was found or created.

Properties
namespacestringRead-onlyminLength 1maxLength 25

Label namespace.

Labels created by calling the Find Or Create Label method 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. It can't be modified, even if displayName is updated.


displayNamestringminLength 1maxLength 180

Label display name shown in the dashboard.


labelTypestringRead-only

Label type indicating how the label was created.


createdDatestringRead-onlyformat date-time

Date and time the label was created.


updatedDatestringRead-onlyformat date-time

Date and time the label was last updated.

Did this help?

GET

List Labels


Lists all contact labels for a site.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Bookings Services and Settings
Manage Contact Labels
Manage Portfolio
Manage Members and Contacts - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/contacts/v4/labels

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

POST

Find Or Create Label


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

Successful calls to this method always return a label, which can be specified in subsequent calls.

For example, in the Contacts API, Label Contact and Unlabel Contact calls will fail if you include a non-existent label. To ensure successful calls, you can call this method first, and then use the response in the Label Contact and Unlabel Contact calls.

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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Members and Contacts - all permissions
Manage Contact Labels
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/contacts/v4/labels

Errors
428Failed Precondition

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:
Did this help?

GET

Get Label


Retrieves a label by the specified label key.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Bookings Services and Settings
Manage Contact Labels
Manage Portfolio
Manage Members and Contacts - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/contacts/v4/labels/{key}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

DELETE

Delete Label


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

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Members and Contacts - all permissions
Manage Contact Labels
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/contacts/v4/labels/{key}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:
Did this help?

PATCH

Update Label


Renames a label.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Members and Contacts - all permissions
Manage Contact Labels
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/contacts/v4/labels/{label.key}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:
Did this help?

POST

Query Labels


Retrieves a list of contact labels. Up to 1,000 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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Bookings Services and Settings
Manage Contact Labels
Manage Portfolio
Manage Members and Contacts - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/contacts/v4/labels/query

Errors
400Invalid Argument

There are 6 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

Contact Label Created


Triggered when a label is created.

Permissions
Manage Bookings Services and Settings
Manage Contact Labels
Manage Portfolio
Manage Members and Contacts - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
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.


createdEventCreatedEvent

Event information.

Did this help?

Contact Label Deleted


Triggered when a label is deleted.

Permissions
Manage Bookings Services and Settings
Manage Contact Labels
Manage Portfolio
Manage Members and Contacts - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
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.

Did this help?

Contact Label Updated


Triggered when a label is updated.

Permissions
Manage Bookings Services and Settings
Manage Contact Labels
Manage Portfolio
Manage Members and Contacts - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
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.


updatedEventUpdatedEvent

Event information.

Did this help?