Skip to content

API search parameters

Filters and other search parameters can be used with API functions that returns a list of records.

Examples

PHP

$url = 'Lead';

$where = [
    [
        'type' => 'isNotNull',
        'attribute' => 'assignedUserId',
    ],
    [
        'type' => 'or',
        'value' => [
            [
                'type' => 'equals',
                'attribute' => 'status',
                'value' => 'New',
            ],
            [
                'type' => 'equals',
                'attribute' => 'status',
                'value' => 'Assigned',
            ],
        ],
    ],
];

$boolFilterList = [
    // 'onlyMy',
    // 'followed',
];

// the list of available primary filters can obtained in a select manager class
$primaryFilter = 'primaryFilter';

// every param is optional
$params = [
    'offset' => 0,
    'maxSize' => 20,
    'where' => $where,
    'primaryFilter' => $primaryFilter,
    'boolFilterList' => $boolFilterList,
    'select' => 'id,name,assignedUserId,status', 
    'orderBy' => 'createdAt',
    'order' => 'desc',
];

$response = $client->request('GET', $url, $params);

Javascript (Nodejs)

// every param is optional
var params = {
    maxSize: 5,
    primaryFilter: 'open',
    where: [
        {
            type: 'equals',
            attribute: 'priority',
            value: 'Urgent',
        }
    ],
    select: 'id,name,assignedUserId,assignedUserName',
};

client.request('GET', 'Case', params)
    .then(
        (response) => {
            console.log(response);
        }
    )

Python

params = {
    "select": "id,phoneNumber",
    "where": [
        {
            "type": "equals",
            "attribute": "phoneNumber",
            "value": '+1',
        },
    ],
}
result = client.request('GET', 'Account', params)

Params

offset

Integer

An offset for pagination.

maxSize

Integer

How much records to return.

select

String

What record attributes to return. Separated by comma. Whitespaces are not allowed. Specify only attributes that you need, it can improve performance.

Example: id,name,status,assignedUserId.

where

Array

Search criteria. Can contain nested arrays and objects. See more below more detail.

primaryFilter

String

A primiry filter. Primary filters are usualy defined in Select Manager class.

boolFilterList

Array

Bool filters. E.g. onlyMy, followed.

orderBy

String

An attribute to order by.

order

String

A direction of order: 'desc' or 'asc'.

Where items

Where parameter is an array if items, that can contain nested items. The data should be URL-encoded. API clients provided in the documentation handle encoding.

Examples below are given in JSON format for readability.

equals, notEquals

{
    "type": "equals",
    "attribute": "status",
    "value": "New"
}

greaterThan, lessThan, greaterThanOrEquals, lessThanOrEquals

{
    "type": "greaterThan",
    "attribute": "amountConverted",
    "value": 1000.00
}

isNull, isNotNull

{
    "type": "isNull",
    "attribute": "assignedUserId"
}

isTrue, isFalse

{
    "type": "isTrue",
    "attribute": "someBoolField"
}

linkedWith, notLinkedWith

For link-multiple fields.

{
    "type": "linkedWith",
    "attribute": "teams",
    "value": ["someTeamId"]
}

isLinked, isNotLinked

For link-multiple fields. Whether is linked or not linked with any record.

{
    "type": "isLinked",
    "attribute": "teams"
}

in, notIn

{
    "type": "in",
    "attribute": "status",
    "value": ["New", "Assigned"]
}

contains, notContains, startsWith, endsWith, like, notLike

{
    "type": "contains",
    "attribute": "someTextOrVarcharField",
    "value": "text"
}

or, and

{
    "type": "or",
    "value": [
        {
            "type": "equals",
            "attribute": "status",
            "value": "New"
        },
        {
            "type": "equals",
            "attribute": "status",
            "value": "Assigned"
        }
    ]
}

today, past, future, lastSevenDays, currentMonth, lastMonth, nextMonth, currentQuarter, lastQuarter, currentYear, lastYear, currentFiscalYear, lastFiscalYear, currentFiscalQuarter, lastFiscalQuarter

{
    "type": "today",
    "attribute": "someDateField"
}

lastXDays, nextXDays, olderThanXDays, afterXDays,

{
    "type": "lastXDays",
    "attribute": "someDateField",
    "value": 2
}

between

{
    "type": "between",
    "attribute": "someNumberOrDateField",
    "value": [100, 200]
}

arrayAnyOf, arrayNoneOf, arrayAllOf

For array, multi-enum, checkbox fields.

{
    "type": "arrayAnyOf",
    "attribute": "fieldName",
    "value": ["Value 1", "Value 2"]
}

arrayIsEmpty, arrayIsNotEmpty

For array, multi-enum, checkbox fields.

{
    "type": "arrayIsEmpty",
    "attribute": "fieldName"
}

Attribute names

Attribute names usually are same as a system field names. Fields are listed at Administration > Entity Manager > ... > Fields.

Attribute names should be in lowerCamelCase.

More info about attributes here.