Skip to main content

Retrieve Multiple Resources

The Multiple Retrieve method fetches a collection of entities from Deepser using an HTTP GET request. You can narrow results with filters, logical operators, and pagination parameters. This section covers the full query syntax.

Syntax​

HTTP Method: GET

URL:

http://deepserhost/api/rest/[entities]?[filters]&[parameters]

Example​

The following request retrieves up to two companies whose names start with "ACME":

URL:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=2

Response:


					{
    "totalRecords": 3,
    "items": [
        {
            "entity_id": "1",
            "parent_id": "0",
            "sort_order": null,
            "name": "ACME International",
            "description": "ACME International - Main Company of the group",
            "phone": "0288396",
            "fax": "998266",
            "address": "Madison Square Garden",
            "city": "NY",
            "state": "NY",
            "country": "USA",
            "zip_code": "00195",
            "notes": null,
            "logo": "company/image/a/c/acme_usa.png",
            "primary_contact": "4\\euclid",
            "mailbox_id": "0",
            "status": "1",
            "formtemplate_id": "56",
            "updated_at": "2018-07-12 08:43:13",
            "created_at": "2018-06-19 13:30:41",
            "payment_status": null
        },
        {
            "entity_id": "2",
            "parent_id": "1",
            "sort_order": null,
            "name": "ACME France",
            "description": "ACME France",
            "phone": null,
            "fax": null,
            "address": "Roux de Strasse",
            "city": "Paris",
            "state": "Paris",
            "country": "France",
            "zip_code": "75000",
            "notes": null,
            "logo": "company/image/a/c/acme_fr_1.png",
            "primary_contact": "4\\euclid",
            "mailbox_id": "0",
            "status": "1",
            "formtemplate_id": "56",
            "updated_at": "2018-07-12 08:43:56",
            "created_at": "2018-06-19 13:33:57",
            "payment_status": null
        }
    ]
}

The response contains:

  • totalRecords -- the total number of matching records (which may exceed the limit value).
  • items -- a JSON array of entity objects, limited by the limit parameter when specified.

Filters​

Filters let you retrieve a subset of records, similar to a SQL WHERE clause. Parameters such as limit and order control pagination and sorting, similar to SQL clauses.

Basic Filter Syntax​

Append a filter array to the query string. Each filter element requires an attribute key that specifies the target field:

http://deepserhost/api/rest/companies?filter[1][attribute]=field

Then add an operator key with the comparison value:

http://deepserhost/api/rest/companies?filter[1][attribute]=field&filter[1][operator]=value

Where:

  • filter -- the filter array; the index (e.g., 1) groups the attribute and operator together
  • operator -- the comparison type (see the full list below)
  • value -- the value to match against

Example: Filter by Name​

Retrieve all companies with a name starting with "ACME":

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%

Combining Multiple Filters​

Add more elements to the filter array to filter on multiple fields:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=country&filter[2][eq]=USA

This returns all companies whose name starts with "ACME" and whose country equals "USA".

Filter Operators​

The following operators are available:

  • eq -- "equal to" -- returns items where the attribute equals the specified value.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%
  • neq -- "not equal to" -- returns items where the attribute does not equal the specified value.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][neq]=ACME
  • in -- "equals any of" -- returns items matching any of the specified values.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][in]=ACME

For multiple values, use an additional array:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][in][0]=ACME&filter[1][in][1]=Contoso
  • nin -- "not equals any of" -- excludes items matching any of the specified values.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nin][1]=ACME&filter[1][nin][2]=International
  • gt -- "greater than" -- returns items where the attribute is greater than the specified value.
http://deepserhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][gt]=0
  • lt -- "less than" -- returns items where the attribute is less than the specified value.
http://deepdeskhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][lt]=1
  • like -- "like" -- returns items where the attribute matches the specified pattern. Use SQL LIKE wildcard syntax (% for any characters).
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%
  • nlike -- "not like" -- returns items where the attribute does not match the specified pattern.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%
  • from, to -- specifies a range of values (inclusive).
http://deepserhost/api/rest/companies?filter[1][attribute]=parent_id&filter[1][from]=2&filter[1][to]=3

Logical Operators​

You can combine filters using AND and OR logic.

AND Conditions​

Define multiple filter elements. Each filter is joined with AND logic:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&filter[2][attribute]=parent_id&filter[2][gt]=0

OR Conditions (Same Field)​

Use multiple index arrays within the same filter element:

http://deepserhost/api/rest/companies?filter[1][attribute]=entity_id&filter[1][0][eq]=1&filter[1][1][eq]=3

OR Conditions (Different Fields)​

Use the following syntax to apply OR logic across different fields:

http://deepserhost/api/rest/companies?filter[0][attribute][0]=name&filter[0][attribute][1]=parent_id&filter[0][0][like]=%ACME%&filter[0][1][eq]=1

Parameters​

The following parameters control pagination and sorting:

  • page -- the page number of results to return.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&page=2
  • order -- the field name to sort results by.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • dir -- the sort direction: asc for ascending, dsc for descending.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&order=name&dir=asc
  • limit -- the maximum number of items to return. The default is 10 and the maximum is 100.
http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][nlike]=ACME%&limit=100
tip

If an attribute value contains spaces, encode each space as %20:

http://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][eq]=ACME%20International%20LTS