# List suggestions

Resolve a name or phrase to the value a search filter needs: organisations, job titles and event vocabulary.

Canonical: https://chikaraintel.com/docs/api/reference/search/list-suggestions

```text
GET https://api.chikaraintel.com/v1/search/suggestions
```

Authentication: `Authorization: Bearer <token>`.

## Parameters

- `query` (string, query) The name or phrase to resolve. Matches a substring.
- `page` (integer, query) 1-based page number. Default `1`.
- `limit` (integer, query) Rows per page, up to 100. A larger value is capped at 100, not rejected. Default `20`.

## Response

The payload is under `success`, with paging details under `meta`.

- `fieldType` (string) `Organisation`, `Occupation`, `MoveType`, `EventType`, `DealStatus` or `DealType`.
- `label` (string) What to show a user.
- `value` (string) A reference for `Organisation` and `Occupation`, the exact value otherwise.
- `operator` (string) Always `Equal`.

People are not included. Use [GET /v1/profiles](/docs/api/reference/profiles/list-profiles) to find a person.

## Examples

cURL:

```bash
curl -sS -G "https://api.chikaraintel.com/v1/search/suggestions" \
  -H "Authorization: Bearer $CHIKARA_API_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "query=Chief Financial" \
  --data-urlencode "limit=20" \
  --data-urlencode "page=1"
```

JavaScript:

```javascript
const BASE = "https://api.chikaraintel.com";
const headers = {
  Authorization: `Bearer ${process.env.CHIKARA_API_TOKEN}`,
  Accept: "application/json"
};

const limit = 50;
const maxPages = 20; // hard cap
const rows = [];

for (let page = 1; page <= maxPages; page++) {
  const params = new URLSearchParams({
    query: "Chief Financial",
    limit: String(limit),
    page: String(page)
  });
  const res = await fetch(`${BASE}/v1/search/suggestions?${params}`, { headers });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

  const { success } = await res.json();
  rows.push(...success);
  if (success.length < limit) break; // a short page is the last page
}

console.log(rows.length, rows[0]);
```

Python:

```python
import os
import requests

BASE = "https://api.chikaraintel.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['CHIKARA_API_TOKEN']}",
    "Accept": "application/json",
}

LIMIT = 50
MAX_PAGES = 20  # hard cap
rows = []

for page in range(1, MAX_PAGES + 1):
    res = requests.get(
        f"{BASE}/v1/search/suggestions",
        headers=HEADERS,
        params={
            "query": "Chief Financial",
            "limit": LIMIT,
            "page": page,
        },
        timeout=30,
    )
    res.raise_for_status()
    batch = res.json()["success"]
    rows.extend(batch)
    if len(batch) < LIMIT:  # a short page is the last page
        break

print(len(rows), rows[:1])
```

Response:

```json
{
  "status": {
    "code": 200,
    "messages": []
  },
  "success": [
    {
      "fieldType": "Occupation",
      "label": "Chief Financial Officer",
      "value": "7d0e1f2a-b4c5-4d6e-9f8a-b9c0d1e2f3d1",
      "operator": "Equal"
    }
  ],
  "meta": {
    "total": 1,
    "rows_per_page": 20,
    "page": 1,
    "total_pages": 1,
    "links": {
      "first-page": {
        "href": "/v1/search/suggestions?page=1",
        "method": "GET"
      },
      "current-page": {
        "href": "/v1/search/suggestions?page=1",
        "method": "GET"
      }
    }
  },
  "correlation_id": "5f0c2a9e4b7d4c1e"
}
```

## Used by

- resolve_search_terms