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).

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!