# List companies

`GET /api/v1/customers`

Filters, sorts and pages active companies. `counts` gives customer / prospect totals and overdue visits for the filtered list.

## Query parameters

| Field | Type | Description |
|---|---|---|
| `scope` | string | `mine` = records I own (default for sales users), `all` = every record I can see (default for admins), or a user id. |
| `status` | string | `AC` = active customer, `Prospect` = prospect. Values: `AC`, `Prospect` |
| `q` | string | Name, city or sector contains. |
| `city` | string | City (exact match). |
| `visit` | string | Visit schedule state. Values: `overdue`, `soon`, `ok`, `none` |
| `risk` | string | `1` = only customers at risk. |
| `active` | string | `0` = inactive (archived) companies. |
| `sort` | string | Sort order. Values: `name`, `visit`, `priority` |
| `page` | integer | Page number (starts at 1). |
| `per` | integer | Rows per page (10–100). |

## Response

```json 200
{
  "counts": {
    "ac": 9,
    "overdue": 1,
    "prospect": 21,
    "soon": 0
  },
  "ok": true,
  "page": 1,
  "pages": 3,
  "rows": [
    {
      "active": true,
      "at_risk": false,
      "city": "Adana",
      "currency": "EUR",
      "currency_default": "",
      "id": 9,
      "initials": "KP",
      "last_visit": "2026-07-02",
      "main_contact": {
        "email": "ayse.aydin@kumsalplastik.example",
        "name": "Ayşe Aydın",
        "phone": "0 (322) 000 80 24",
        "wa": "903220008024"
      },
      "name": "Kumsal Plastik Ambalaj San. ve Tic. A.Ş.",
      "next_visit_due": "2026-09-30",
      "open_opps": 0,
      "owner": {
        "full_name": "Deniz Aksoy",
        "id": 1,
        "role": "admin",
        "role_label": "Yönetici",
        "username": "admin"
      },
      "pending_state": null,
      "period": 90,
      "phone": "0 (322) 000 53 49",
      "potential_kg": 12000.0,
      "rid": "001t29x5kWbHOxg",
      "sector": "Esnek ambalaj",
      "status": "AC",
      "status_label": "Aktif Müşteri",
      "unit": "kg",
      "visit_overdue_days": 2,
      "visit_state": "overdue"
    },
    {
      "active": true,
      "at_risk": false,
      "city": "Konya",
      "currency": "EUR",
      "currency_default": "",
      "id": 8,
      "initials": "IF",
      "last_visit": "2026-08-25",
      "main_contact": {
        "email": "gizem.arslan@isiltifilm.example",
        "name": "Gizem Arslan",
        "phone": "0 (332) 000 94 28",
        "wa": "903320009428"
      },
      "name": "Işıltı Film A.Ş.",
      "next_visit_due": "2026-11-23",
      "open_opps": 0,
      "owner": {
        "full_name": "Deniz Aksoy",
        "id": 1,
        "role": "admin",
        "role_label": "Yönetici",
        "username": "admin"
      },
      "pending_state": null,
      "period": 90,
      "phone": "0 (332) 000 99 70",
      "potential_kg": 40000.0,
      "rid": "001frrIzBuo8ERp",
      "sector": "Film üretimi",
      "status": "AC",
      "status_label": "Aktif Müşteri",
      "unit": "kg",
      "visit_overdue_days": -52,
      "visit_state": "ok"
    }
  ],
  "total": 30
}
```