About the Labels API
The Labels API provides functionality for managing labels for your site. Labels allow site admins to segment or categorize the contacts in their Contact List. Using Labels enchances the CRM by allowing site admins to customize data organization according to their needs. For example, you can use labels to target specific audiences for email campaigns or bulk actions. Learn more about labels.
With the Labels API, you can:
Terminology
- Label: A tag that is applied to contacts to help site admins organzie 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 site admins.
- System-defined label: A label that is pre-defined in your site and cannot be deleted from the CRM.
Setup
To use the Labels API, install the @wix/crm package using npm or Yarn:
1npm install @wix/crm
or
1yarn add @wix/crm
Then import { labels } from @wix/crm:
1import { labels } from '@wix/crm'
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.
The deleteLabel() function returns a Promise that resolves when the specified label is deleted.
Permission Scopes
For app development, you must have one of the following permission scopes:function deleteLabel(key: string): Promise<void>
Label key to delete.
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.
The findOrCreateLabel() function returns a Promise that resolves when the specified label is found or created.
Successful calls to findOrCreateLabel() always returns a label, which can be passed to subsequent function calls.
To find an existing label without potentially creating a new one, use getLabel() or queryLabels().
Permission Scopes
For app development, you must have one of the following permission scopes:function findOrCreateLabel(displayName: string, options: FindOrCreateLabelOptions): Promise<FindOrCreateLabelResponse>
Display name to retrieve or create.
If an existing label is an exact match for the specified display name, the existing label is returned. If not, a new label is created and returned.
Language options.
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 by the specified label key.
The getLabel() function returns a Promise that resolves when the specified label is retrieved.
Permission Scopes
For app development, you must have one of the following permission scopes:function getLabel(key: string, options: GetLabelOptions): Promise<ContactLabel>
Label key.
key is generated when the label is created. It cannot be modified, even if displayName is updated.
Language options.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a query to retrieve a list of labels.
The queryLabels() function builds a query to retrieve a list of labels and returns a LabelsQueryBuilder object.
The returned object contains the query definition, which is used to run the query using the find() function.
You can refine the query by chaining LabelsQueryBuilder functions onto the query. LabelsQueryBuilder functions enable you to filter, sort, and control the results that queryLabels() returns.
queryLabels() runs with the following LabelsQueryBuilder defaults, which you can override:
skip(0)limit(50)descending('_createdDate')
The following LabelsQueryBuilder functions are supported for queryLabels(). For a full description of the Labels object, see the object returned for the items property in LabelsQueryResult.
| PROPERTY | SUPPORTED FILTERS & SORTING |
|---|---|
namespace | eq(),ne() |
key | eq(),ne(),in() |
displayName | eq(),ne(),in(),startsWith(),ascending(),descending() |
labelType | eq() |
_createdDate | eq(),ne(),gt(),lt(),ge(),le(),ascending(),descending() |
_updatedDate | eq(),ne(),gt(),lt(),ge(),le(),ascending(),descending() |
Permission Scopes
For app development, you must have one of the following permission scopes:function queryLabels(options: QueryLabelsOptions): LabelsQueryBuilder
Language options.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Renames a label.
The renameLabel() function returns a Promise that resolves when the specified label's display name is changed.
Permission Scopes
For app development, you must have one of the following permission scopes:function renameLabel(key: string, label: RenameLabel, options: RenameLabelOptions): Promise<ContactLabel>
Label key.
key is generated when the label is created. It cannot be modified, even if displayName is updated.
Label to rename.
Language options.