> 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

# QueryLabels

# Package: contacts

# Namespace: ContactLabelsServiceV4

# Method link: https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/labels/query-labels.md

## Permission Scopes:
Manage Contact Labels: SCOPE.DC-CONTACTS.MANAGE-LABELS

## Introduction

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](https://dev.wix.com/api/rest/contacts/labels/sort-and-filter). To learn how to query labels, see
[API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).

---

## REST API

### Schema

```
 Method: queryLabels
 Description: 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](https://dev.wix.com/api/rest/contacts/labels/sort-and-filter). To learn how to query labels, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).
 URL: https://www.wixapis.com/contacts/v4/labels/query
 Method: POST
 Method parameters:
   param name: language | type: language | description: Language for localization. 2-letter language code in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) format. 
   param name: query | type: Query   
        - name: filter | type: object | description: ilter object.  Possible filters: `$eq`, `$gt`, `$gte`, `$in`, `$lt`, `$lte`, `$ne`, `$startsWith`.  For a detailed list of supported filters, see [sorting and filtering for labels](https://dev.wix.com/api/rest/contacts/labels/sort-and-filter).  Example: `{ "filter": { "displayName": { "$startsWith": "Referral" } } }` 
        - name: sort | type: array<Sorting> | description: Sorting options. For a list of fields that can be sorted, see [sorting and filtering for labels](https://dev.wix.com/api/rest/contacts/labels/sort-and-filter).  Example: `{ "sort": [{"fieldName": "displayName", "order": "DESC"}] }` 
           - name: fieldName | type: string | description: Name of the field to sort by. 
           - name: order | type: SortOrder | description: Sort order.  Default: `ASC`. 
                 - enum:
                 -     ASC: Sort by ascending order.
                 -     DESC: Sort by descending order.
        - name: paging | type: Paging | description: Pagination options. 
           - name: limit | type: integer | description: Number of items to return.  Defaults to `1000`. <br> Maximum: `2000`. 
           - name: offset | type: integer | description: Number of items to skip in the current sort order. 
 Return type: QueryLabelsResponse
  - name: labels | type: array<ContactLabel> | description: List of labels 
     - name: namespace | type: string | description: Label namespace.  Labels created by calling the Find Or Create Label method are automatically assigned to the `custom` namespace. 
     - name: namespaceDisplayName | type: string | description: Display name for the namespace, used to organize the list of labels in the site dashboard. 
     - name: key | type: string | description: Label key.  `key` is generated when the label is created. It can't be modified, even if `displayName` is updated. 
     - name: displayName | type: string | description: Label display name shown in the dashboard. 
     - name: labelType | type: LabelType | description: Label type indicating how the label was created. 
         - enum:
         -     SYSTEM: Default system label for the contact list.
         -     USER_DEFINED: Label created by calling the Find Or Create Label method.
         -     WIX_APP_DEFINED: Label created by an app built by Wix.
     - name: createdDate | type: string | description: Date and time the label was created. 
     - name: updatedDate | type: string | description: Date and time the label was last updated. 
  - name: pagingMetadata | type: PagingMetadata | description: Details on the paged set of results returned. 
     - name: count | type: integer | description: Number of items returned. 
     - name: offset | type: integer | description: Requested offset. 
     - name: total | type: integer | description: Number of items that matched the query. 
     - name: tooManyToCount | type: boolean | description: Indicates if `total` calculation timed out before the response was sent. Typically this happens if there is a large set of results. 

 Possible Errors:
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER_VALUE | Description: Unsupported filter value.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER_OPERATOR | Description: Unsupported filter operator for the provided field.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER_FIELD | Description: Unsupported filter field.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER | Description: At least 1 of the provided filters isn't supported.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: MALFORMED_FILTER | Description: Filter couldn't be parsed.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_SORT | Description: Unsupported sort field.


```

### Examples

### Query All Labels
```curl
curl -X POST \
  'https://www.wixapis.com/contacts/v4/labels/query' \
  -H 'Authorization: <AUTH>'
```

### Query Labels by Namespace Sorted by CreatedDate Desc
```curl
curl -X POST \
  'https://www.wixapis.com/contacts/v4/labels/query' \
  -H 'Authorization: <AUTH>'
  --data-binary '{
    "query": {
      "filter": {
        "namespace" : "custom"
      },
      "sort" :
      [
        {"fieldName": "createdDate", "order" : "DESC"}
      ]
    }
  }'
```

### Query Labels by Keys
```curl
curl -X POST \
  'https://www.wixapis.com/contacts/v4/labels/query' \
  -H 'Authorization: <AUTH>'
  --data-binary '{
    "query": {
      "filter": {
        "key" : {
          "$in" : ["custom.my-label", "contacts.contacted-me"]
        }
      }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.contacts.ContactLabelsServiceV4.queryLabels(query, options)
 Description: 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](https://dev.wix.com/api/rest/contacts/labels/sort-and-filter). To learn how to query labels, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  query
 Method parameters: 
   param name: options | type: QueryLabelsOptions  none 
        - name: language | type: string | description: Language for localization. 2-letter language code in [ISO 639-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) format. 
   param name: query | type: LabelQuery   | required: true
        - name: filter | type: object | description: ilter object.  Possible filters: `$eq`, `$gt`, `$gte`, `$in`, `$lt`, `$lte`, `$ne`, `$startsWith`.  For a detailed list of supported filters, see [sorting and filtering for labels](https://dev.wix.com/api/rest/contacts/labels/sort-and-filter).  Example: `{ "filter": { "displayName": { "$startsWith": "Referral" } } }` 
        - name: sort | type: array<Sorting> | description: Sorting options. For a list of fields that can be sorted, see [sorting and filtering for labels](https://dev.wix.com/api/rest/contacts/labels/sort-and-filter).  Example: `{ "sort": [{"fieldName": "displayName", "order": "DESC"}] }` 
           - name: fieldName | type: string | description: Name of the field to sort by. 
           - name: order | type: SortOrder | description: Sort order.  Default: `ASC`. 
                 - enum:
                 -     ASC: Sort by ascending order.
                 -     DESC: Sort by descending order.
        - name: paging | type: Paging | description: Pagination options. 
           - name: limit | type: integer | description: Number of items to return.  Defaults to `1000`. <br> Maximum: `2000`. 
           - name: offset | type: integer | description: Number of items to skip in the current sort order. 
 Return type: PROMISE<QueryLabelsResponse>
  - name: labels | type: array<ContactLabel> | description: List of labels 
     - name: namespace | type: string | description: Label namespace.  Labels created by calling the Find Or Create Label method are automatically assigned to the `custom` namespace. 
     - name: namespaceDisplayName | type: string | description: Display name for the namespace, used to organize the list of labels in the site dashboard. 
     - name: key | type: string | description: Label key.  `key` is generated when the label is created. It can't be modified, even if `displayName` is updated. 
     - name: displayName | type: string | description: Label display name shown in the dashboard. 
     - name: labelType | type: LabelType | description: Label type indicating how the label was created. 
         - enum:
         -     SYSTEM: Default system label for the contact list.
         -     USER_DEFINED: Label created by calling the Find Or Create Label method.
         -     WIX_APP_DEFINED: Label created by an app built by Wix.
     - name: _createdDate | type: Date | description: Date and time the label was created. 
     - name: _updatedDate | type: Date | description: Date and time the label was last updated. 
  - name: pagingMetadata | type: PagingMetadata | description: Details on the paged set of results returned. 
     - name: count | type: integer | description: Number of items returned. 
     - name: offset | type: integer | description: Requested offset. 
     - name: total | type: integer | description: Number of items that matched the query. 
     - name: tooManyToCount | type: boolean | description: Indicates if `total` calculation timed out before the response was sent. Typically this happens if there is a large set of results. 

 Possible Errors:
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER_VALUE | Description: Unsupported filter value.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER_OPERATOR | Description: Unsupported filter operator for the provided field.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER_FIELD | Description: Unsupported filter field.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: UNSUPPORTED_FILTER | Description: At least 1 of the provided filters isn't supported.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: MALFORMED_FILTER | Description: Filter couldn't be parsed.
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_SORT | Description: Unsupported sort field.


```

### Examples

### Add labels to a contact form as checkbox options (with $w)
This function uses `queryLabels()` to retrieve specific labels and then uses those label's display names as checkbox options for a checkbox group element on a contact form.

```javascript
/*************************************
 * Backend code - contacts.web.js/ts *
 ************************************/

import { Permissions, webMethod } from '@wix/web-methods';
import { labels } from '@wix/crm';
import { auth } from '@wix/essentials';

export const addLabelsAsCheckboxOptions = webMethod(Permissions.Anyone, async () => {

  try {
    // Query specific labels to use as checkbox options
    const elevatedQueryLabels = auth.elevate(labels.queryLabels);
    const myLabels = await elevatedQueryLabels()
    .startsWith('displayName', "Contact by")
    .find();

    return myLabels.items

  } catch (error) {
    console.log(error);
    // Handle the error
  }
});

/*************
 * Page code *
 *************/

import { addLabelsAsCheckboxOptions } from 'backend/labelsBackend.web';

// Trigger when the email input field on a contact form is clicked
export async function inputEmail_click_1(event) {

  try {
    let checkboxLabelOptions = [];
    const labels = await addLabelsAsCheckboxOptions();

    // Add label display names to the array used to hold the checkbox options
    labels.forEach(item => {
      checkboxLabelOptions.push({label: item.displayName, value: item.key});
    });

    // Set the checkbox group options as the label display names
    $w('#checkboxGroup2').options = checkboxLabelOptions;
    // Display the checkbox group element on the form
    $w('#checkboxGroup2').show();
  } catch (error) {
    console.log(error)
  }
}

```

### Retrieve labels with specified `labelType` (with elevated permissions)
```javascript
import { labels } from '@wix/crm';
import { auth } from '@wix/essentials';

export async function myQueryLabelsFunction() {
  try {
    const elevatedQueryLabels = auth.elevate(labels.queryLabels);
    const queryResults = await elevatedQueryLabels()
      .eq("labelType", "USER_DEFINED")
      .find();

    const items = queryResults.items;
    const firstItem = items[0];
    const pageSize = queryResults.pageSize;
    const hasNext = queryResults.hasNext();
    const hasPrev = queryResults.hasPrev();
    const length = queryResults.length;
    const query = queryResults.query;
    console.log('Retrieved items:', items);
    
    return items;
  } catch (error) {
    console.log(error);
    // Handle the error

  }
}

/* Returns items:
 * [
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.at-risk",
 *     "displayName": "At Risk",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
 *     "_createdDate": "2023-12-25T08:38:36.000Z",
 *     "_updatedDate": "2023-12-25T08:38:36.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.active-customer",
 *     "displayName": "Active Customer",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
 *     "_createdDate": "2023-12-25T06:13:21.000Z",
 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.contact",
 *     "displayName": "Contact",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "5fec05f8-eb03-4243-ad46-4c24535144f6",
 *     "_createdDate": "2023-12-11T07:33:35.000Z",
 *     "_updatedDate": "2023-12-11T07:33:35.000Z"
 *   }
 * ]
 */
```

### Retrieve labels with specified `labelType`
```javascript
import { labels } from '@wix/crm';

export async function myQueryLabelsFunction() {
  try {
    const queryResults = await labels.queryLabels()
      .eq("labelType", "USER_DEFINED")
      .find();

    const items = queryResults.items;
    const firstItem = items[0];
    const pageSize = queryResults.pageSize;
    const hasNext = queryResults.hasNext();
    const hasPrev = queryResults.hasPrev();
    const length = queryResults.length;
    const query = queryResults.query;
    console.log('Retrieved items:', items);
    
    return items;
  } catch (error) {
    console.log(error);
    // Handle the error

  }
}

/* Returns items:
 * [
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.at-risk",
 *     "displayName": "At Risk",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
 *     "_createdDate": "2023-12-25T08:38:36.000Z",
 *     "_updatedDate": "2023-12-25T08:38:36.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.active-customer",
 *     "displayName": "Active Customer",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
 *     "_createdDate": "2023-12-25T06:13:21.000Z",
 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.contact",
 *     "displayName": "Contact",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "5fec05f8-eb03-4243-ad46-4c24535144f6",
 *     "_createdDate": "2023-12-11T07:33:35.000Z",
 *     "_updatedDate": "2023-12-11T07:33:35.000Z"
 *   }
 * ]
 */
```

### Retrieve all labels (with elevated permissions)
```javascript
import { labels } from '@wix/crm';
import { auth } from '@wix/essentials';

const elevatedQueryLabels = auth.elevate(labels.queryLabels);

export async function myQueryLabelsFunction() {
  
  try {
    const queryResults = await elevatedQueryLabels()
      .find();

    const items = queryResults.items;
    const firstItem = items[0];
    const pageSize = queryResults.pageSize;
    const hasNext = queryResults.hasNext();
    const hasPrev = queryResults.hasPrev();
    const length = queryResults.length;
    const query = queryResults.query;
    console.log('Retrieved items:', items);
    
    return items;
  } catch (error) {
    console.log(error);
    // Handle the error

  }
}

/* Returns items:
 * [
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.at-risk",
 *     "displayName": "At Risk",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
 *     "_createdDate": "2023-12-25T08:38:36.000Z",
 *     "_updatedDate": "2023-12-25T08:38:36.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.active-customer",
 *     "displayName": "Active Customer",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
 *     "_createdDate": "2023-12-25T06:13:21.000Z",
 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.contact",
 *     "displayName": "Contact",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "5fec05f8-eb03-4243-ad46-4c24535144f6",
 *     "_createdDate": "2023-12-11T07:33:35.000Z",
 *     "_updatedDate": "2023-12-11T07:33:35.000Z"
 *   },
 *   {
 *     "namespace": "contacts",
 *     "namespaceDisplayName": "Labels",
 *     "key": "contacts.customers",
 *     "displayName": "Customers",
 *     "labelType": "SYSTEM",
 *     "legacyId": "contacts_server/customers"
 *   },
 *   {
 *     "namespace": "contacts",
 *     "namespaceDisplayName": "Labels",
 *     "key": "contacts.contacted-me",
 *     "displayName": "Contacted Me",
 *     "labelType": "SYSTEM",
 *     "legacyId": "contacts_server/contacted_me"
 *   }
 * ]
 */
```

### Retrieve all labels
```javascript
import { labels } from '@wix/crm';

export async function myQueryLabelsFunction() {
  
  try {
    const queryResults = await labels.queryLabels()
      .find();

    const items = queryResults.items;
    const firstItem = items[0];
    const pageSize = queryResults.pageSize;
    const hasNext = queryResults.hasNext();
    const hasPrev = queryResults.hasPrev();
    const length = queryResults.length;
    const query = queryResults.query;
    console.log('Retrieved items:', items);
    
    return items;
  } catch (error) {
    console.log(error);
    // Handle the error

  }
}

/* Returns items:
 * [
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.at-risk",
 *     "displayName": "At Risk",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
 *     "_createdDate": "2023-12-25T08:38:36.000Z",
 *     "_updatedDate": "2023-12-25T08:38:36.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.active-customer",
 *     "displayName": "Active Customer",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
 *     "_createdDate": "2023-12-25T06:13:21.000Z",
 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
 *   },
 *   {
 *     "namespace": "custom",
 *     "namespaceDisplayName": "Labels",
 *     "key": "custom.contact",
 *     "displayName": "Contact",
 *     "labelType": "USER_DEFINED",
 *     "legacyId": "5fec05f8-eb03-4243-ad46-4c24535144f6",
 *     "_createdDate": "2023-12-11T07:33:35.000Z",
 *     "_updatedDate": "2023-12-11T07:33:35.000Z"
 *   },
 *   {
 *     "namespace": "contacts",
 *     "namespaceDisplayName": "Labels",
 *     "key": "contacts.customers",
 *     "displayName": "Customers",
 *     "labelType": "SYSTEM",
 *     "legacyId": "contacts_server/customers"
 *   },
 *   {
 *     "namespace": "contacts",
 *     "namespaceDisplayName": "Labels",
 *     "key": "contacts.contacted-me",
 *     "displayName": "Contacted Me",
 *     "labelType": "SYSTEM",
 *     "legacyId": "contacts_server/contacted_me"
 *   }
 * ]
 */
```

### queryLabels (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 { labels } from '@wix/crm';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { labels },
  // Include the auth strategy and host as relevant
});


async function queryLabels(query,options) {
  const response = await myWixClient.labels.queryLabels(query,options);
};
```

---