Modifiers are queries that affect the format of the response object. Note that all the below listed modifiers are valid only for GET requests.

By default (if no modifiers are applied), the response object will contain a maximum of 20 items sorted by the id field in ascending order and consisting of a pre-defined set of fields and associations.

Contents

The following modifiers are supported by the API at the moment:

Fields

The fields modifier allows specifying a list of fields and/or associations that the response object(s) must contain.

FormatExampleResponse Object Will HaveComments
wildcard ?fields=*
?fields=[]		 All available fields.
All available associations with default formatting.		 Simple (one-to-one) associations will be formatted as items. Complex associations will be formatted as collections of items.
comma-separated values ?fields=firstName,status Specified fields and/or associations + the id field. If any of the specified fields/associations does not exist within the collection, an error response will be returned.
nested ?fields=*,status[timestamp] All available fields + specified associations with requested formatting. Nested format can be applied only to associations.

It is possible to specify what fields/associations should be included into the association object by listing the required fields inside the square brackets []. Note that simple associations within the association object will always be formatted as items and complex associations – as collections of items.

Examples

ModifierResponse Object Will Have
?fields=*,[] All fields and all associations with default formatting.
?fields=*,[*] All fields and all associations formatted as items or collections of items.
?fields=firstName,workgroups Fields id and firstName + workgroups association with default formatting.
?fields=phone,[] Fields id and phone + all associations formatted as a single item identifier or collections of item identifiers.
?fields=phone,[],workgroups[] Fields id and phone + workgroups association formatted as a collection of item identifiers + all other associations formatted as a single item identifier or collections of item identifiers.
?fields=phone,[*],workgroups[] Fields id and phone + workgroups association formatted as a collection of item identifiers + all other associations formatted as a single item or collections of items.
?fields=phone,[],workgroups[name] Fields id and phone + workgroups association formatted a collection of items (each of which containing the only id and name fields) + all other associations formatted as a single item identifier or collections of item identifiers.
?fields=phone,[],workgroups[name,customers[*]] Formatting error (nested brackets are not supported – nested associations will always be formatted as item identifiers or collections of item identifiers).
?fields=*,[],[*] Formatting error (square brackets must be either empty or containing the wildcard symbol).

Page

The page modifier allows splitting large numbers of collection items into several pages. This modifier can be applied only to collections.

FormatExampleResponse ObjectComments
one value ?page=3 The response object will contain the default number of records (items) per page. The default number is 20 records per page.
two values ?page=3,25 The response object will contain the specified number of records (items) per page. The maximum number of records per page cannot exceed 100.

The response object will always contain a metadata object with the following values:

ValueDescription
page Current page number.
pageCount Total number of pages.
recordsCount Total number of records available.
recordsPerPage Maximum number of records per each page.

Examples

ModifierResponse Object Will Have
?page=15 A slice of collection containing records with index numbers from 301 to 320 (note that the index numbers are not the items' identifiers).
?page=15,5 A slice of collection containing records with index numbers from 76 to 80 (since now there are only 5 records per page).
?page=15,200 Parsing error (the maximum number of records per page cannot exceed 100).
?page=0 Formatting error (the page number must be positive).

Where

The where modifier allows specifying custom filtration criteria to be applied to a collection. This modifier can be applied only to collections. Note that not all fields/associations may support filtering.

FormatExampleMeaning
fieldName operator value [join operator] ?where=firstName is "John" Get only entities with field firstName equal to John
associationName.fieldName operator value [join operator] ?where=company.name startsWith "eco" Get only entities with field name of association company beginning with eco

The filters can be applied only to fields/associations that support filtering. Non-numeric values and lists must be put inside double quotes "" (use the backslash \ symbol to escape inner quotes).

The following operators are supported at the moment:

OperatorMeaningExampleRestrictions
=
==
is
eq
equalTo		 Equal to ?where=firstName = "John"
?where=firstName == "John"
?where=firstName is "John"
?where=firstName eq "John"
?where=firstName equalTo "John"		  
!=
<>
isNot
neq
notEqualTo		 Not equal to ?where=firstName != "John"
?where=firstName <> "John"
?where=firstName isNot "John"
?where=firstName neq "John"
?where=firstName notEqualTo "John"		  
>
gt
greaterThan		 Greater than ?where=timestamp > 1372206671
?where=timestamp gt 1372206671
?where=timestamp greaterThan 1372206671		 Only supported for numeric fields.
>=
gte
greaterThanOrEqualTo		 Greater than or equal to ?where=timestamp >= 1372206671
?where=timestamp gte 1372206671
?where=timestamp greaterThanOrEqualTo 1372206671		 Only supported for numeric fields.
<
lt
lessThan		 Less than ?where=timestamp < 1372206671
?where=timestamp lt 1372206671
?where=timestamp lessThan 1372206671		 Only supported for numeric fields.
<=
lte
lessThanOrEqualTo		 Less than or equal to ?where=timestamp <= 1372206671
?where=timestamp lte 1372206671
?where=timestamp lessThanOrEqualTo 1372206671		 Only supported for numeric fields.
~
contains		 Contains ?where=firstName ~ "Jo"
?where=firstName contains "Jo"		 Case-insensitive.
Not supported for numeric fields.
!~
notContains		 Does not contain ?where=firstName !~ "Jo"
?where=firstName notContains "Jo"		 Case-insensitive.
Not supported for numeric fields.
~%
sw
startsWith
bw
beginsWith		 Starts with ?where=firstName ~% "Jo"
?where=firstName sw "Jo"
?where=firstName startsWith "Jo"
?where=firstName bw "Jo"
?where=firstName beginsWith "Jo"		 Case-insensitive.
Not supported for numeric fields.
%~
ew
endsWith		 Ends with ?where=firstName %~ "Jo"
?where=firstName ew "Jo"
?where=firstName endsWith "Jo"		 Case-insensitive.
Not supported for numeric fields.
^
in		 One of ?where=id ^ (100, 102, 107)
?where=id in (100, 102, 107)		  
!^
nin
notIn		 None of ?where=id !^ (100, 102, 107)
?where=id nin (100, 102, 107)
?where=id notIn (100, 102, 107)		  

The modifier allows using various functions for values. The list of supported functions is as follows:

FunctionDescriptionExampleResult
My(fieldName) Retrieve value of the specified field of the current user's identity object. My("firstName") John
LowerCase(value) Convert all characters of the value to lower case. LowerCase("Test") test
UpperCase(value) Convert all characters of the value to upper case. UpperCase("Test") TEST
Sum(value1, [value2, [...]]) Calculate a sum of all values in the list. Sum(1, 2, 3, 4) 10
Product(value1, [value2, [...]]) Calculate a product of all values in the list. Product(1, 2, 3, 4) 24
DateTime(year, [month,] [day,]
[hour,] [minute,] [second])		 Convert a date into the Unix timestamp. DateTime(2013, 8, 23, 15, 52, 27) 1377229947
DateTimeFormat(time, [format]) Convert a date of the specified format into the Unix timestamp.
Supported formats: ISO8601, RFC822, RFC850, RFC1036, RFC2822, RFC3339, relative (this format supports natural-language time values like "now" or "-3 months").		 DateTimeFormat("Fri, 23 Aug 2013
15:52:27 +1200", "RFC822")

DateTimeFormat("now", "relative")		 1377229947


1377229947

Note that the modifier can contain more than one condition. The conditions can be joined together using the AND and OR join operators and can also be grouped using round brackets ().

Examples

ModifierResponse Object Will Have
?where=job in (1123,1124,1130) A slice of collection containing records whose job field's value is either 1123, 1124 or 1130.
?where=firstName startsWith "Sam" A slice of collection containing records whose firstName field's value starts with Sam (case-insensitive). The following values satisfy that criteria: Sam, Samuel, Samantha. The following value, however, does not satisfy the criteria: Rosamund.
?where=firstName contains "Sam"
AND firstName isNot "Sam"		 A slice of collection containing records whose firstName field's value contains text Sam (case-insensitive) and is not equal to Sam. The following values satisfy that criteria: Samuel, Samantha, Rosamund. The following values, however, do not satisfy the criteria (note the second condition): Sam, sam.
?where=(firstName contains "Sam"
OR firstName startsWith "Rosa")
AND timestamp < DateTimeFormat(
"-2 months", "relative")		 A slice of collection containing records whose firstName field's value contains text Sam (case-insensitive) or starts with text Rosa and whose date of creation was no later than two months before.

Sort

The sort modifier allows sorting the requested collection by specified fields and/or associations. The modifier can be applied only to collections. Note that not all fields/associations may support sorting.

FormatExampleMeaningRestrictions
fieldName ?sort=firstName Sort the entities by the value of the firstName field If sorting type is omitted, then the ascending sorting type will be applied by default.
fieldName[type] ?sort=firstName[desc] Sort the entities by the value of the firstName field in descending order The type value must be either asc (ascending order) or desc (descending order).

Flags

The flags modifier can enable special features. Multiple features can be enabled by listing features in a comma separated list.

Feature NameExampleMeaningRestrictions
recordsCount ?flags=recordsCount

Include a full metadata object on the request with the following values:

- page the page number within the set of records that has been returned

- recordsPerPage the maximum number of records returned in the request

- pagesCount the recordsPerPage / recordsCount

- recordsCount total count of the records identified in the request

 It is advised that you only use the recordsCount flag on the first request as the performance cost can grow on very large data sets. Subsequent page requests need not use the flag.
accountSharing ?flags=accountSharing For accounts that are Partners with sub Child accounts, enabling this well return relevant data from all related accounts. Only available for Partners, a suitable scenario would be franchise reporting