Querying data

Most of our endpoints allows you to retrieve specific data through query requests using various parameters.

Our API also lets you select what properties to return (like an SQL SELECT command), limit the quantity, sort and skip results.

Query paramaters

Example query request

The following request and response payload is an example of a query made to the Contacts API.

try {
  const response = await fetch('https://api.qualyhq.com/v1/contacts?projection=number%20profile.firstName%20profile.lastName%20profile.picture%20email%20profile.phone%20tags%20owners&sort=number&limit=14&skip=0', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

Query response

Note that the _id is automatically included, unless specified otherwise in the projection paramater (e.g. -_id).

{
    "count": 1,
    "hasMore": false,
    "data": [{
        "_id": "653fc651d14vbfe63d4fd49c",
        "email": "email@email.com",
        "number": "123",
        "profile": {
            "firstName": "First name",
            "lastName": "Test",
            "phone": "+61 415 374 585"
        },
        "owners": [
            "64e382f1c79fe62f6fd1546c"
        ],
        "tags": [],
    }]
}

Enconding query paramaters

Objects

You need to encode JavaScript objects by converting key-value pairs into a query string format.

// this object
{ key1: 'value1', key2: 'value2' }

// becomes
'key1=value1&key2=value2'

Arrays

Arrays are handled by encoding their indices or keys.

// this array
[ 'value1', 'value2' ]

// becomes
'0=value1&1=value2'

// or using the brackets notation
'arr[]=value1&arr[]=value2'

Nested objects and arrays

Nested objects or arrays are encoded using dot notation.

// this object
{ key: { nestedKey: 'value' } }

// becomes
'key.nestedKey=value'

Special characters and URI component

Encoding special characters

You need to encode special characters, to allower their inclusion in query strings without causing parsing issues.

For example, spaces are replaced with %20.

URI component encoding

Use URI component encoding for preserving the integrity of URL query parameters. This encoding helps represent characters that have special meanings in URLs by converting them to a valid format.

Expanding responses

Many objects allow you to request additional information as an expanded response by using the population paramater. This parameter is available on most API query requests, and applies to the response of that request only.

To expand responses, add an extra paramater to the URL called population, and using th same enconding as explained above, choose which properties you want to expand.

// this object
[{ path: 'contact', select: 'profile email' }]

// becomes
'0[path]=contact&0[select]=profile email'

Filtering results

You can filter results of your query. Qualy is compatible with the MongoDB query syntax. You can learn more about how to create MongoDB-compatible object queries here.

Note that, aggregation pipelines are not supported.

Search

Some top-level API resources have support for retrieval via our Search API methods. It differs from a "query", as it supports typo-tolerance, free-text search, and more. For example, you can search contacts, and search partnerships.

try {
  const response = await fetch('https://api.qualyhq.com/v1/search/contacts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "query": "test",
    }),
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

Example search results payload

The following payload shows the result of a query request on the contacts entity.

{
    "page": 0,
    "nHits": 1,
    "nPages": 1,
    "hitsPerPage": 14,
    "processingTimeMs": 1,
    "hits": [{
        "_id": "653fc651d14vbfe63d4fd49c",
        "email": "email@email.com",
        "number": "123",
        "profile": {
            "firstName": "First name",
            "lastName": "Test",
        },
        "partnersReference": {},
        "owners": [
            "64e382f1c79fe62f6fd1546c"
        ],
        "primaryTeams": [
            "64e38320c79fe62f6fd154b8"
        ],
        "tags": [],
        "tenantId": "eu1-xpdqxiiphqsdtkpazqdqnraqi",
        "_highlightResult": {
            "email": {
                "value": "email@email.com",
                "matchLevel": "none",
                "matchedWords": []
            },
            "number": {
                "value": "123",
                "matchLevel": "none",
                "matchedWords": []
            },
            "profile": {
                "firstName": {
                    "value": "First name",
                    "matchLevel": "none",
                    "matchedWords": []
                },
                "lastName": {
                    "value": "<em>Test</em>",
                    "matchLevel": "full",
                    "fullyHighlighted": true,
                    "matchedWords": [
                        "test"
                    ]
                }
            }
        },
    }]
}

For the full API reference for the Search endpoint, click here.