> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextoriahub.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Clients API

> Manage client records and portal access via the Nextoria Hub REST API.

## Endpoints

| Method  | Path                       | Description            |
| ------- | -------------------------- | ---------------------- |
| `GET`   | `/v1/clients`              | List all clients       |
| `POST`  | `/v1/clients`              | Create a client        |
| `GET`   | `/v1/clients/:id`          | Get a client           |
| `PATCH` | `/v1/clients/:id`          | Update a client        |
| `POST`  | `/v1/clients/:id/invite`   | Send portal invite     |
| `GET`   | `/v1/clients/:id/projects` | List client's projects |
| `GET`   | `/v1/clients/:id/invoices` | List client's invoices |

***

## List Clients

```bash theme={null}
GET /v1/clients
```

**Example Request:**

```bash theme={null}
curl https://api.nextoriahub.com/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Example Response:**

```json theme={null}
{
  "data": [
    {
      "id": "client_xyz789",
      "name": "Acme Corp",
      "email": "hello@acmecorp.com",
      "company": "Acme Corporation Inc.",
      "portal_access": true,
      "portal_last_seen": "2026-02-28T09:15:00Z",
      "total_billed": 45000,
      "outstanding_balance": 8500,
      "active_projects": 2,
      "created_at": "2025-06-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 34,
    "limit": 20
  }
}
```

***

## Create a Client

```bash theme={null}
POST /v1/clients
```

**Request Body:**

```json theme={null}
{
  "name": "Jane Doe",
  "email": "jane@globexcorp.com",
  "company": "Globex Corporation",
  "phone": "+1 555 000 0000",
  "address": {
    "line1": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "postal_code": "62701",
    "country": "US"
  },
  "notes": "Primary contact for all Globex projects."
}
```

**Required fields:** `name`, `email`

**Response:** `201 Created`

***

## Send Portal Invite

```bash theme={null}
POST /v1/clients/:id/invite
```

Sends a branded portal invitation email to the client.

**Request Body:**

```json theme={null}
{
  "project_ids": ["proj_abc123", "proj_def456"],
  "message": "Welcome to our client portal! You can track your projects and invoices here.",
  "expires_at": "2026-06-01T00:00:00Z"
}
```

**Response:**

```json theme={null}
{
  "invited": true,
  "invite_sent_at": "2026-03-01T10:00:00Z",
  "portal_url": "https://portal.youragency.com"
}
```

***

## Client Object

```typescript theme={null}
interface Client {
  id: string; // "client_xyz789"
  name: string;
  email: string;
  company: string | null;
  phone: string | null;
  address: Address | null;
  notes: string | null;
  portal_access: boolean;
  portal_last_seen: string | null;
  total_billed: number; // Lifetime billed, in minor currency units
  outstanding_balance: number;
  active_projects: number;
  created_at: string;
  updated_at: string;
}

interface Address {
  line1: string;
  line2?: string;
  city: string;
  state: string;
  postal_code: string;
  country: string; // ISO 3166-1 alpha-2
}
```