Clients Abilities

11 abilities for managing MainWP client records and their associated sites.

MainWP registers 11 client management abilities into the WordPress Abilities API framework. These enable programmatic management of client records, site associations, and client-level operations.

What You’ll Learn

• Listing, filtering, and retrieving client information
• Creating, updating, and deleting clients
• Managing client site associations
• Suspending and unsuspending clients
• Retrieving client cost data

---

mainwp/list-clients-v1

List MainWP clients with pagination and filtering.

Method: GET (readonly)

curl -u 'admin:xxxx' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-clients-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
page	integer	No	1	Page number
per_page	integer	No	20	Items per page (max 100)
status	string	No	”any”	Filter: any, active, suspended
search	string	No	""	Search term
include	array	No	[]	Client IDs to include
exclude	array	No	[]	Client IDs to exclude

Response:

{
  "items": [
    {
      "id": 1,
      "name": "Acme Corp",
      "email": "[e-mail]",
      "phone": "[phone]",
      "status": "active",
      "sites_count": 5,
      "created_at": "2023-01-15T10:00:00Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 25
}

---

mainwp/count-clients-v1

Get total count of clients.

Method: GET (readonly)

curl -u 'admin:xxxx' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/count-clients-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
status	string	No	”any”	Filter: any, active, suspended

Response:

{
  "total": 25
}

---

mainwp/get-client-v1

Get detailed information about a single client.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-client-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email address

Response:

{
  "id": 1,
  "name": "Acme Corp",
  "email": "[e-mail]",
  "phone": "[phone]",
  "address_1": "123 Main Street",
  "address_2": "Suite 100",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "country": "United States",
  "note": "Premium client",
  "status": "active",
  "sites_count": 5,
  "created_at": "2023-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

---

mainwp/add-client-v1

Create a new client.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"name":"New Client","client_email":"[e-mail]","client_phone":"[phone]"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/add-client-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
name	string	Yes	—	Client name
client_email	string	No	—	Email address
client_phone	string	No	—	Phone number
address_1	string	No	—	Address line 1
address_2	string	No	—	Address line 2
city	string	No	—	City
state	string	No	—	State/Province
zip	string	No	—	ZIP/Postal code
country	string	No	—	Country
note	string	No	—	Notes
selected_sites	array	No	—	Site IDs to associate

Response:

Returns the created client object (same format as get-client-v1).

---

mainwp/update-client-v1

Update an existing client.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1,"name":"Updated Name","note":"New notes"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/update-client-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email
name	string	No	—	Client name
client_email	string	No	—	Email address
client_phone	string	No	—	Phone number
address_1	string	No	—	Address line 1
address_2	string	No	—	Address line 2
city	string	No	—	City
state	string	No	—	State/Province
zip	string	No	—	ZIP/Postal code
country	string	No	—	Country
note	string	No	—	Notes
selected_sites	array	No	—	Site IDs to associate (replaces existing)

Response:

Returns the updated client object.

---

mainwp/delete-client-v1

Delete a client. This is a destructive operation that requires confirmation.

Method: POST

# Dry run to preview
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1,"dry_run":true}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/delete-client-v1/run'

# Actual deletion
curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1,"confirm":true}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/delete-client-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email
confirm	boolean	Yes	—	Must be true to confirm deletion
dry_run	boolean	No	false	Preview without deleting

Response:

{
  "deleted": true,
  "client_id": 1,
  "client_name": "Acme Corp"
}

---

mainwp/get-client-sites-v1

Get sites associated with a client.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-client-sites-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email
page	integer	No	1	Page number
per_page	integer	No	20	Items per page

Response:

{
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites": [
    {
      "id": 1,
      "url": "https://site1.example.com",
      "name": "Site 1",
      "status": "connected"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 5
}

---

mainwp/count-client-sites-v1

Count sites associated with a client.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/count-client-sites-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email

Response:

{
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites_count": 5
}

---

mainwp/get-client-costs-v1

Get cost tracker entries for a client. Requires the Cost Tracker module to be active.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-client-costs-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email

Response:

{
  "client_id": 1,
  "client_name": "Acme Corp",
  "costs": [
    {
      "id": 1,
      "site_id": 1,
      "site_name": "Site 1",
      "name": "Hosting",
      "amount": 29.99,
      "frequency": "monthly",
      "next_due": "2024-02-15"
    }
  ],
  "total_monthly": 149.95,
  "total_yearly": 1799.40
}

This ability requires the Cost Tracker module. If inactive, returns mainwp_module_not_available error.

---

mainwp/suspend-client-v1

Suspend a client. This also suspends all associated sites.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/suspend-client-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email

Response:

{
  "suspended": true,
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites_suspended": 5
}

---

mainwp/unsuspend-client-v1

Unsuspend a previously suspended client. This also unsuspends all associated sites.

Method: POST

curl -X POST -u 'admin:xxxx' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"client_id_or_email":1}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/unsuspend-client-v1/run'

Input Parameters:

Name	Type	Required	Default	Description
client_id_or_email	integer|string	Yes	—	Client ID or email

Response:

{
  "unsuspended": true,
  "client_id": 1,
  "client_name": "Acme Corp",
  "sites_unsuspended": 5
}

---

Related Resources

• Abilities API Overview - API basics and authentication
• Sites Abilities - Site management abilities
• REST API Clients - REST API alternative for clients
• Manage Clients - Client management in Dashboard