Querying and Filtering API Data with `select`, `search`, and Global Filters

Docusnap365 REST API supports query parameters to customize API responses and retrieve only the necessary data.
Using select, search, and global filters, you can:

Retrieve specific fields instead of full objects.
Filter results based on defined criteria.
Improve response clarity and reduce unnecessary data transfer.

Select Parameter

The select parameter allows you to specify which fields should be included in the response.

Key Points:

Property names are case-sensitive.
Supports JSONPath ($) for selecting nested fields.

Basic Example: Selecting Specific Fields

GET /api/v2/segment/hardware?select=["name","serial"]

Example Response

[
  {
    "name": "HP EliteDesk 800 G3",
    "serial": "ABC12345XYZ"
  }
]

Why Use `select`?

Retrieves only the required fields.
Reduces response size by excluding unnecessary data.

💡 API Explorer Tip:
Enter values without ?select=, just ["name"] in the input field.

Using JSONPath (`$`) in `select`

JSONPath enables retrieving specific nested data within the response.

Example: Extracting `account_AssetInformation` from a Datasource

GET /api/v2/datasources/{id}?select=["$.account_AssetInformation[*]"]

Response

{
  "account_AssetInformation": [
    {
      "name": "pha@itelio.com",
      "type_RawData": "e49d5926-804a-46bd-b5cb-30dc58f056d6",
      "id": "0062ce0a3df1d727189625522664fc2797a9067c6c053251f3903f6757b4f446"
    }
  ]
}

Use When:

Retrieving only nested properties inside an object.
Selecting structured data from an endpoint like /datasources/{id}.

Search Parameter

The search parameter filters results based on specific criteria.

Key Features:

Supports exact matches, wildcards, multiple filters, and JSONPath ($).
Property names are case-sensitive.

Basic Filtering Example

GET /api/v2/segment/hardware?search=["name=*EliteDesk*"]

Matches:

✅ "HP EliteDesk 800 G3"
✅ "EliteDesk Pro Mini"

Why Use `search`?

Retrieves only results matching the defined criteria.
Supports wildcards (*, ?) and exact matches.

Using JSONPath (`$`) in `search`

JSONPath allows filtering within specific nested fields instead of searching across all properties.

Example: Searching for `name` inside `account_AssetInformation` (Datasources Endpoint)

GET /api/v2/datasources/{id}?search=["$.account_AssetInformation[*].name=*paul*"]

Why Use This?

Searches only within account_AssetInformation.name, avoiding matches in unrelated fields.
More precise filtering when working with complex data structures.

Global Filters (Organizations, Domains, Sites, Platforms)

These filters allow efficient retrieval of specific subsets of data in list endpoints (e.g., GET /api/v2/segment/hardware).

Parameter	Description
organizations	Filters by organization ID
sites	Filters by site ID
domains	Filters by domain ID
platform	Filters by platform ID

Example Usage

GET /api/v2/segment/hardware?organizations=052600aa-0699-4eeb-af5a-7dc03a4ce436

Why Use Global Filters?

Filter by organization, site, platform or domain.
More efficient than search operations and easier to use.

⚠
Global filters are just supported in:

GET List endpoints (/segment/{segment})

GET By type endpoints (/segment/{segment}/type/{typeId})

Combining Parameters

You can combine multiple parameters for refined results.

Example Usage

GET /api/v2/segment/hardware?select=["name","serial"]&search=["userDefined=true"]&organizations=052600aa-0699-4eeb-af5a-7dc03a4ce436

✅ This request:

Returns only name and serial fields.
Filters by userDefined=true.
Limits results to a specific organization.

💡 Best Practice:

Use global filters (organizations, sites, etc.) when available.
When global filters are not supported, use search instead.

Key Takeaways

select → Choose specific fields to include in the response (supports JSONPath).
search → Filter results based on properties (supports JSONPath for nested filtering).
Global Filters → Efficiently filter by organization, site, etc.
Combine Parameters → Use select, search, and global filters together for precise queries.

With these query options, you can refine API requests to get exactly the data you need!