Using Query Parameters

You can use query parameters to specify various conditions for retrieving resource records.

This topic contains the following sections:

Supported Query Parameters

The following table lists the query parameters that are supported in the Connect REST API.

Parameter Description

download

Supported only with the fileAttachment resource, for example, see Downloading Individual File Attachments.

expand

Returns a fully expanded version of a particular subresource. See Retrieving Expanded Resource Data.

fields

Returns only the specified, comma-separated list of fields for collection resources, such as incidents or contacts, or for individual objects. The fields query parameter supports dotted notation.

  • Collection resources. Use the GET method with the following query syntax to return data for multiple objects:
    https://your_site_interface/services/rest/connect/v1.4/resource?fields=field1,field2,...
  • Objects. Use the GET method with the following query syntax to return data for a single object:
    https://your_site_interface/services/rest/connect/v1.4/resource/resource_id?fields=field1,field2,...

Note:

Queries on subfields, such as name.first, only work with individual resources and not with collections.

limit

Sets the page size. See Paginating.

links

Returns only the specified, comma-separated set of links for a particular object.

Use GET with the following query syntax:

https://your_site_interface/services/rest/connect/v1.4/resource/resource_id?links=link_type1,link_type2,...

offset

Determines the record number from which to start retrieval. See Paginating.

orderBy

Determines the sort order of results. See Sorting.

q

See Using ROQL Object Queries.

query

Supported only with the queryResults resource. See Using ROQL Tabular Queries.

totalResults

Lets you display the total number of results. See Paginating.

Resource Example for fields Parameter

Using GET with the following query:

https://mysite.example.com/services/rest/connect/v1.4/incidents?fields=subject,language,severity

returns the following data:

{
    "items": [
        {
        "id": 1,
        "lookupName": "100909-000000",
        "createdTime": "2013-08-21T21:13:23Z",
        "updatedTime": "2013-11-11T21:00:25Z",
        "subject": "How do I access my voicemail outside of my home calling area?",
        "severity": {},
        "links": [
            {
            "rel": "canonical",
            "href": "https://day26-151100-sql-164h.qb.lan/services/rest/connect/v1.4/incidents/1"
            }
            ]
        },
        {
        "id": 2,
        "lookupName": "100909-000001",
        "createdTime": "2013-08-21T21:15:50Z",
        "updatedTime": "2013-11-11T21:00:14Z",
        "subject": "Power surge recovery",
        "severity": {},
        "links": [
            {
            "rel": "canonical",
            "href": "https://day26-151100-sql-164h.qb.lan/services/rest/connect/v1.4/incidents/2"
            }
            ]
        },
        ...
        {
        "id": 66,
        "lookupName": "150929-000002",
        "createdTime": "2015-09-29T20:17:11Z",
        "updatedTime": "2015-09-29T20:17:11Z",
        "subject": "Help! Accidentally reset my phone!",
        "severity": {},
        "links": [
            {
            "rel": "canonical",
            "href": "https://day26-151100-sql-164h.qb.lan/services/rest/connect/v1.4/incidents/66"
            }
        ]
        }
    ],
    "hasMore": false,
    "links": [
        {
        "rel": "alternate",
        "href": "https://day26-151100-sql-164h.qb.lan/services/rest/connect/v1.4/incidents",
        "mediaType": "application/schema+json"
        },
        {
        "rel": "canonical",
        "href": "https://day26-151100-sql-164h.qb.lan/services/rest/connect/v1.4/incidents"
        },
        {
        "rel": "describedby",
        "href": "https://day26-151100-sql-164h.qb.lan/services/rest/connect/v1.4/metadata-catalog/incidents",
        "mediaType": "application/schema+json"
        },
        {
        "rel": "self",
        "href": "https://day26-151100-sql-164h.qb.lan/services/rest/connect/v1.4/incidents"
        }
    ]
}

Object Example for fields Parameter

Using GET with the following query:

https://mysite.example.com/services/rest/connect/v1.4/accounts/7
?fields=id,lookupName,name.first,profile

returns the following metadata about the account with ID 7:

{
    "id": 7,
    "lookupName": "George Hewitt",
    "name": {
        "first": "George"
        },
    "profile": {
        "id": 12,
        "lookupName": "Customer Support Manager"
        },
    "links": [
        {
        ...
        }
    ]
}

Example for links Parameter

Using GET with the following query:

https://mysite.example.com/services/rest/connect/v1.4/accounts/7?links=self,alternate

returns the following data about the account with ID 7:

{
    "id": 7,
    "lookupName": "George Hewitt",
    ...
    "signature": null,
    "staffGroup": {
        "id": 100022,
        "lookupName": "Customer Support - Tier 1"
        },
    "links": [
        {
        "rel": "self",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/7"
        },
        {
        "rel": "alternate",
        "href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/7",
        "mediaType": "application/schema+json"
        }
    ]
}