Skip to main content

Content control

Lisa Wong
Updated

Use query strings with GET requests to control the data that is returned.

Note:

Use the appropriate regional endpoint to ensure that you comply with your organization's privacy policy, and applicable laws and regulations. For details about the available regional endpoints, and how to identify your organization's region, see Shared responsibility.

Fields

The fields query string parameter can be used to specify precisely what fields are returned for a resource. This parameter is valid for both instance and collection responses.

Example

You want to request that only the id and name fields are returned for a Member Variable in the response.

To create this request, append the URL with the fields query string after the resource (memberVariable):

https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?fields=id,name

For details about the /membervariable resource, see Member Data Service.

Paging

When requesting large amounts of data, you can group the results into smaller chunks. When used together, the limit and offset query string parameters allow you to effectively page through the results. This parameter is valid for collection responses only.

The following table describe the query string parameters:
Parameter Description
limit The maximum number of items that will be returned per page in the response. The default is 20 and the maximum is 1000.
offset The number of items that were skipped for the current page of results.

Example

You want the response to return 40 items per page. To do this:

  1. Append the URL after the resource (memberVariables) with the limit parameter set to return the first 40 items and the offset parameter set to start with the first item (?limit=40&offset=0).

    https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?limit=40&offset=0

  2. Create another request to return the next 40 results beginning at the 41st item (?limit=40&offset=40).

    https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?limit=40&offset=40

  3. Continue to create requests until the total number of items has been reached.

    See the Response Payload section on how to determine the total number of items.

Sorting

Use the sort query string parameter to sort the data in ascending or descending order.

This parameter is valid for Collection responses only.

The query string format is as follows:

/{resource}?sort={fieldName}:{a|d}

The following table describes the query string components:

Component Description
{resource} The name of the resource.
{fieldName} The name of the field you would like the results sorted on.
{a|d} Refers to ascending (a) or descending (d) sorts. The default sorting order is ascending.
Tip: The sort query string parameter supports multiple fields. For example, ?sort=effectiveDate,lastUpdateDate

Example

You want to sort the name field on the memberVariables resource in descending order. To do this append ?sort=name:d to the URL after the resource:

https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?sort=name:d

See Member Data Service for details on the memberVariables resource.

Note: When sorting, the order of records with the same sort values can be different each time. Be aware that these records can appear on a different page if the records overlap with the offset value.

Filtering

You can filter your results for specific values. Filtering is valid for Collection responses only. The format is as follows:

GET https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/{resource}?{fieldA}={valueA}&{fieldB}={valueB}

The following describes the components of the query string:

Component Description
{resource} The name of the resource.
{fieldA} The name of the fields to filter on.
{fieldB}
{valueA} The single values or comma-separated lists of values to match.
{valueB}

Filter example

You want your request to only return Member Variables that have a name of email or city. To do this, append the email and city fields (?name=email,city) to the end of the URL after the resource (/membervariables).

https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?name=email,city

See Member Data Service section for details on the memberVariables resource.

Depending the on the endpoint, you can filter the response on an array of nested fields.

Filter on an array example

You want to filter the concepts in a dataset based on the question type in the tags field. To do this, append the field name to the end of the URL followed by .contains and the field value.

GET https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/datasets/{datasetId}/concepts?q=%22tags.contains(%22singlechoice%22)%22

You can also use the query string parameter q to build complex conditions to filter on a specific value, values in a range, or a combination of conditions.

Query string example

If today's date is November 16, 2016, then the following request will return all the activities that are scheduled to be closed today or thereafter.

GET https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/activities?q="closedOn>="2016-11-16T00:00:00Z""

Tip: If the query string parameter q does not work, encode its value in the URL. Using the above URL example, the encoded version will be:

https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/activities?q=%22closedOn%3E%3D%222016-11-16T00%3A00%3A00Z%22%22

For more information, see HTML URL Encoding Reference.

The following table lists the operations supported by the parameter q:

Operation type Operation name Operators Example
Equality Equal = or eq or %3D ?q="status="open""
Not Equal != or neq or %21= ?q="status neq "open""
Less than < or lt or %3C ?q="closedOn<"2016-11-16T00:00:00Z""
Less than or equal <= or le or %3C= ?q="closedOn le "2016-11-16T00:00:00Z""
Greater than > or gt or %3E ?q="closedOn>"2016-11-16T00:00:00Z""
Greater than or equal >= or ge or %3E= ?q="closedOn ge "2016-11-16T00:00:00Z""
Logic Intersection of results and ?q="openedOn>="2016-11-01T00:00:00Z" and openedOn<"2016-12-01T00:00:00Z""
Union of results or ?q="status="pending" or status="open""
String Match from the end {field}.EndsWith("{match string}") ?q="name.EndsWith("test")"
Contains {field}.Contains("{match string}") ?q="name.Contains("satisfaction")"
Match from the beginning {field}.StartsWith("{match string}") ?q="name.StartsWith("2016")"

Headers

Use headers to authenticate the API and return an entity.

Header Description
X-WebApi-Return-Resource If the value of this header is set to true then the entity (or entities) will be returned in the response payload for POST, PUT and PATCH requests.

If false then the entity will not be returned.

Parent topic: Making requests
Related information

Related articles

Powered by Zendesk