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

# Clients Endpoints

> Route-level reference for MainWP REST API v2 client endpoints, including client CRUD, client fields CRUD, client-site/cost lookups, and client batch operations.

Use these endpoints to manage clients and custom client fields in MainWP Dashboard.

<Note>
  Use the [MainWP Postman collection](https://www.postman.com/mainwp/mainwp/collection/ujfddk4/mainwp-rest-api-v2-current) as the source of truth for request and response schemas.
</Note>

`{id_or_email}` accepts either a numeric client ID or a client email.

## Route Matrix

### Client Records

| Method           | Path                                 | Purpose                           | Key Params                                                   |
| ---------------- | ------------------------------------ | --------------------------------- | ------------------------------------------------------------ |
| GET              | `/clients`                           | List clients                      | `page`, `per_page`, `search`, `include`, `exclude`, `status` |
| GET              | `/clients/count`                     | Count clients                     | Collection filters                                           |
| POST             | `/clients/add`                       | Create a client                   | `name`, `client_email`, optional address/contact fields      |
| GET              | `/clients/{id_or_email}`             | Get one client                    | `id_or_email`                                                |
| POST, PUT, PATCH | `/clients/{id_or_email}/edit`        | Edit a client                     | Editable client fields                                       |
| DELETE           | `/clients/{id_or_email}/remove`      | Delete a client                   | `id_or_email`                                                |
| GET              | `/clients/{id_or_email}/sites`       | List client sites                 | `id_or_email`                                                |
| GET              | `/clients/{id_or_email}/sites/count` | Count client sites                | `id_or_email`                                                |
| GET              | `/clients/{id_or_email}/costs`       | List client costs                 | `id_or_email`                                                |
| POST, PUT, PATCH | `/clients/{id_or_email}/suspend`     | Suspend client                    | `id_or_email`                                                |
| POST, PUT, PATCH | `/clients/{id_or_email}/unsuspend`   | Unsuspend client                  | `id_or_email`                                                |
| POST             | `/clients/batch`                     | Batch client create/update/delete | `create[]`, `update[]`, `delete[]`                           |

### Client Fields

| Method     | Path                               | Purpose               | Key Params                                         |
| ---------- | ---------------------------------- | --------------------- | -------------------------------------------------- |
| GET        | `/clients/fields`                  | List client fields    | `search`, `include`, `exclude`, `page`, `pre_page` |
| POST       | `/clients/fields/add`              | Create a client field | `name`, `description`                              |
| PUT, PATCH | `/clients/fields/{id_name}/edit`   | Edit a client field   | `name`, `description`                              |
| DELETE     | `/clients/fields/{id_name}/delete` | Delete a client field | `{id_name}` (field id or field name)               |

***

## Representative Requests

### Create a client

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme","client_email":"ops@acme.com","client_phone":"+1-555-0100"}' \
  "https://your-dashboard.com/wp-json/mainwp/v2/clients/add"
```

```json theme={null}
{
  "success": 1,
  "message": "Client added successfully.",
  "data": {
    "id": 34,
    "name": "Acme",
    "client_email": "ops@acme.com"
  }
}
```

### Create a client field

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Account Manager","description":"Primary owner"}' \
  "https://your-dashboard.com/wp-json/mainwp/v2/clients/fields/add"
```

```json theme={null}
{
  "success": 1,
  "message": "Client field created successfully.",
  "data": {
    "field_id": 6,
    "name": "Account Manager",
    "description": "Primary owner"
  }
}
```

***

## Related Resources

* [REST API Overview](/api-reference/rest-api/overview)
* [Sites Endpoints](/api-reference/rest-api/sites)
* [Costs Endpoints](/api-reference/rest-api/costs)
* [Batch Endpoint](/api-reference/rest-api/batch)