# List organisations

Search organisations by name and filter by industry, country, status, activity and score.

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

```text
GET https://api.chikaraintel.com/v1/organisations
```

Authentication: `Authorization: Bearer <token>`.

## Parameters

- `name` (string, query) A substring of the organisation's name.
- `show_empty` (string, query) Search every organisation. Without it, only organisations with recorded activity are searched, and that index is refreshed periodically. **Set it for name lookups.** Values: `true`.
- `industry` (integer, query) An industry ID. Matches the industry and every industry below it.
- `country` (string, query) A two-letter code (`GB`) or a country name.
- `type` (string, query) Funds are excluded by default. `fund` returns only funds, `all` returns everything. Values: `fund`, `all`.
- `status` (string, query) Filter by status. Values: `active`, `merged`, `dormant`, `dissolved`, `unknown`, `all`.
- `verified` (boolean, query) `true` or `false`.
- `min_confidence` (integer, query) Minimum confidence, 0 to 100. Defaults to 5 unless `show_empty=true`.
- `has_raum` (boolean, query) Only organisations with (or without) AUM records.
- `activity_type` (string, query) Comma-separated: `move`, `funding`, `public_offering`, `client_summary`.
- `activity_period` (string, query) Only organisations with activity in this period. Values: `week`, `month`, `quarter`, `year`.
- `score_min` (integer, query) Minimum score, 1 to 100.
- `score_dimension` (string, query) The score `score_min` applies to. Values: `growth_momentum`, `financial_strength`, `industry_health`, `management_strength`, `customer_sentiment`, `ipo_readiness`, `ma_attractiveness`.
- `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`.

- `reference` (uuid)
- `name` (string)
- `size` (string) A headcount band, or `-`.
- `totals` (object) `{ employees }`, the recorded headcount.
- `status` (string)
- `verified` (boolean)
- `confidence` (integer) 0 to 100.

## Examples

cURL:

```bash
curl -sS -G "https://api.chikaraintel.com/v1/organisations" \
  -H "Authorization: Bearer $CHIKARA_API_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "name=Halberd" \
  --data-urlencode "show_empty=true" \
  --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({
    name: "Halberd",
    show_empty: "true",
    limit: String(limit),
    page: String(page)
  });
  const res = await fetch(`${BASE}/v1/organisations?${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/organisations",
        headers=HEADERS,
        params={
            "name": "Halberd",
            "show_empty": "true",
            "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": [
    {
      "reference": "3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01",
      "name": "Halberd Industrial Group",
      "size": "Large (1,001–5,000 employees)",
      "totals": {
        "employees": 3200
      },
      "status": "active",
      "verified": true,
      "confidence": 88
    },
    {
      "reference": "3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b02",
      "name": "Halberd Industrial Group PLC",
      "size": "-",
      "totals": {
        "employees": 0
      },
      "status": "active",
      "verified": false,
      "confidence": 41
    }
  ],
  "meta": {
    "total": 2,
    "rows_per_page": 20,
    "page": 1,
    "total_pages": 1,
    "links": {
      "first-page": {
        "href": "/v1/organisations?page=1",
        "method": "GET"
      },
      "current-page": {
        "href": "/v1/organisations?page=1",
        "method": "GET"
      }
    }
  },
  "correlation_id": "5f0c2a9e4b7d4c1e"
}
```

## Used by

- search_companies