---
title: "Find entities by name or ID"
type: reference
method: GET
path: /rest-api/suggest-items.do
tag: "Search"
---

# Find entities by name or ID

`GET https://YOUR-NETWORK-DOMAIN/rest-api/suggest-items.do`

Searches sites, zones, placements, advertisers, campaigns and banners whose name contains the query (substring match), or finds one entity by ID when the query is '#<id>' (e.g. '#123'). A 32-character hex query also matches a placement by its placement key. Deleted entities are never returned; banners under moderation (NEW, PENDING or REJECTED) are, unlike in the console's search box, and every banner carries its approvalStatus. At most 100 results come back, sorted by name. Narrow the search with 'entities' (entity types), 'myItems' / 'shareType' (sharing relationship), 'affiliateOnly', or 'filterPath' (a branch of the hierarchy). If no entity types are given, the types the user may search are used. Returns an empty list unless the user can view both inventory and campaigns. Each result carries id, name, type, categoryId, categoryName, inactive and pending, plus approvalStatus (NEW, PENDING, APPROVED or REJECTED) on banners, and the ids of its parents: advertiserId on a campaign, advertiserId and campaignId on a banner, siteId on a zone, siteId and zoneId on a placement. With includeActive=true each result also carries active, the entity's on/off switch. 'inactive' is not the on/off switch: it is true when the entity has no traffic in the daily statistics for the current and previous two days (refreshed hourly), so a switched-on entity with no recent traffic is inactive=true. 'pending' is always false.

## Query params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `query` | string | yes | `summer` | Search query string for matching entity names. Prefix with '#' to search by entity ID (e.g. '#123'). Required. |
| `myItems` | boolean | no | `false` | When true, restricts results to only entities owned by the authenticated user. Defaults to false. |
| `entities` | array<string> | no | `ADVERTISER` | Array of entity types to search in. Accepted values: SITE, ZONE, PLACEMENT, BANNER, CAMPAIGN, ADVERTISER. When omitted, searches all entity types the user has permission to access. |
| `shareType` | array<string> | no | `IS_OWNER` | Array of share type filters to restrict results by sharing relationship. When omitted and myItems is false, no share type filter is applied. |
| `filterPath` | string | no | `1001` | Inventory path ID to scope the search within a specific branch of the entity hierarchy (e.g. an advertiser ID to find only its campaigns). When omitted, searches across the entire inventory. |
| `affiliateOnly` | boolean | no | `false` | When true, restricts results to only affiliate-type entities. Defaults to false. |
| `includeActive` | boolean | no | `true` | When true, every result also carries active — whether the entity is switched on. Defaults to false. |

## Responses

- `200` — JSON array of matches with id, name, type, categoryId, categoryName, inactive (true = no traffic in the last ~2 days, regardless of the on/off state), pending (always false), the parents' ids, approvalStatus on banners and, with includeActive=true, active
- `400` — Bad request - query parameter is missing or null
- `401` — Authentication error - invalid hash, timestamp, or username
- `403` — Forbidden — insufficient permissions

## Example request

```bash
curl --request GET \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/suggest-items.do?query=summer&myItems=false&entities=ADVERTISER&shareType=IS_OWNER' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

Source: https://epom.com/ad-server/docs/api/search/get-suggest-items