Clients

Créer, lire, mettre à jour et gérer les clients (entreprises) de votre agence.

• Readlist_clientsList the client businesses this agency manages, newest first. This is the starting point for anything about clients: use it to find a client and its id before calling get_client_by_id, or to answer questions like "how many active clients do we have?", "which clients are assigned to a rep?", or "show clients with a health score under 40". All filters are optional and are combined together (a client must match all of them); status, representativeIds, and goals each accept multiple values and match any of them. Returns a page of client summaries plus a running `total` and a `nextCursor` — each summary has the client's name, industry, status, goal, health score, number of locations, Google rating and review count, plan, created date, and assigned representative. To page through more, call again passing the returned `nextCursor`. You don't pass an agency — it comes from your credentials. Sensitive data (login credentials, portal secrets) is never returned.
• Readlist_client_plansThe plans you can assign to a client — the values `clientPlanId` accepts on create_client and update_client. Each has its id, name, whether it is the agency's default (used when you omit clientPlanId), and what it includes (`includes`, plus `features` with the per-feature UI and agent access). Archived plans are not listed because they can't be assigned. No pricing is shown.
• Readget_client_by_idGet the full details of a single client by its clientId. Use this once you know which client you want — typically after list_clients gives you the id — when the list summary isn't enough. Returns everything about that one client: full business profile and contact info, the assigned representative and who created the client, health score and rating/review metrics, whether the customer-portal invite is pending or accepted, listings data, and which plan the client is on. You don't pass an agency — it comes from your credentials, and a client from another agency is never returned. Sensitive data (login credentials, portal secrets) is never included. To look up or find a client id first, use list_clients.
• Writecreate_clientAdd a new client (a business your agency will manage) and run its onboarding automatically — it assigns a plan, sets up the client's customer-portal login, and computes an initial health score. You must provide three things: the business name, the client's primary contact email (this becomes their portal login and can't be changed later), and the id of the team member who will own the client. Optionally include Google Business details (get them from search_google_business) to fill in the profile, and a tracking keyword to start monitoring the client's local search rank. IMPORTANT: when you pass a placeId, this also creates the client's FIRST LOCATION from that Google place — which is what starts the listings, reviews and AEO work — and returns its id as `locationId`. Do not follow this with create_location_from_google or create_location for the same business: that would create a duplicate location. If you passed a placeId and `locationId` still comes back null, `locationSkipped` says why (for example `location_limit` means the agency is at its plan's location cap, and the client will have no listings or reviews until a location is added) — tell the user rather than retrying. Fails if a client with the same business name already exists (including an archived one — the error names its id so you can call reactivate_client instead of creating a new one). New clients are visible to your whole team. You don't pass an agency — it comes from your credentials.
• Writeupdate_clientEdit an existing client's editable fields. Pass only the fields you want to change. The client's primaryContactEmail (their portal login) can be filled in once, while it is still blank (pass it here), and can never be changed after that. Identify the client by its id (from list_clients, create_client, or — for an archived client, which list_clients and get_client_by_id never return — the id create_client's duplicate_archived error names). Works on an archived client too, without reactivating it first. Returns the updated client, or throws if not found. You don't pass an agency — it comes from your credentials.
• Writedelete_clientRequest deletion of a client. This never permanently destroys anything. If the client has any locations this SCHEDULES it: the client and every one of its locations are archived at the end of the current billing period, and until then everything stays fully active and still billed — the archival can be called off with cancel_scheduled_client_deletion while it's still pending, or undone with reactivate_client once it has actually archived. A client with no locations at all (or none still live) is archived immediately instead of being scheduled (also undoable with reactivate_client). The response's `outcome` field says which happened ("scheduled" or "archived") — report that back rather than assuming. A client that is already scheduled is left unchanged and returns `outcome: "scheduled"` with `alreadyScheduled: true`. Identify the client by its id (from list_clients).
• Writecancel_scheduled_client_deletionCall off a pending client deletion, so a client scheduled to archive at the end of the billing period carries on as normal. This also releases the locations that were scheduled along with it. Only works while the deletion is still pending — once the period has ended and the client is actually archived, call reactivate_client instead.
• Writereactivate_clientRestore an archived client, bringing back the client and every location that archived along with it in the same request (a location archived separately, before or independently of that request, is not touched). Undoes what delete_client's schedule did once it actually reached the end of the billing period (a still-PENDING one should use cancel_scheduled_client_deletion instead — this tool is for a client that is already archived). A client that isn't currently archived is left unchanged rather than erroring. Find the id with list_clients and archived: "archived" (each summary says it is archived). get_client_by_id deliberately does not return archived clients.
• Writeinvite_clientSend (or resend) the client-portal invite email to a client's primary contact — a passwordless magic link they use to log into their customer portal. Resending does NOT invalidate a previously sent link: every link minted stays independently valid until it's used once or reaches its own 7-day expiry, so a resend leaves both the old and new email usable. Fails if the client has no primaryContactEmail set. Identify the client by its id (from list_clients). Returns the invite link that was sent.
• Readsearch_google_businessSearch Google for a business by name and return the top matches, each enriched with full details (name, address, addressComponents, phone, website, GBP URL, category, businessStatus, rating, reviewCount, placeId, latitude, longitude). Use to find a business to onboard, then pass the chosen match's fields to create_client. Returns an empty list if nothing matches or Google is unavailable.
• Readlist_google_accountsList the Google Business Profile accounts already connected for a client, so you can pick one to import locations from. Returns each account's connectionId, the signed-in email, whether its credentials are still valid, its fetch status, how many locations are already connected, and how many have been fetched and are available to import. Start here for a Google import; if an account has 0 available, call trigger_google_fetch, then get_google_listings. You don't pass an agency — it comes from your credentials.
• Writetrigger_google_fetchStart fetching the locations under a connected Google account so they become browsable/importable. This runs in the background; poll list_google_accounts and watch the account's fetchStatus and available count, then call get_google_listings. Starts (or restarts) the background fetch and returns once it's queued. You don't pass an agency — it comes from your credentials.
• Readget_google_listingsBrowse cached Google locations and folders, with names, addresses, verification, connection/import state and category support. Omit folder for folders and fetch progress; use __ungrouped__ for ungrouped rows, or __all__ with a search for account-wide name search. Folder search matches name, address and postal code. Returns capped/incomplete signals. It never calls Google live: use trigger_google_fetch to refresh first.
• Writecreate_location_from_googleImport one or more fetched Google locations into new business locations under a client, pulling their full Google profile (name, address, hours, categories, photos, etc.). Get the fetchedListingIds from get_google_listings. Imports up to 10 per call. Each new location is submitted to the other directories automatically (it's already live on Google). Returns the created location ids (and any that failed, with the reason). You don't pass an agency — it comes from your credentials.
• Readget_client_creditsRead one client's credits as shown in Clients: given, used, remaining, last addition, and the latest 50 credit-history entries. Read-only. Returns credits and names, without internal usage quantities, provider costs or credit configuration. Requires an identified agency user with Clients page access and access to this client.
• Writeadd_client_creditsAdd positive whole credits to one client's wallet, matching the Clients Add credits action. credits must be 1–1,000,000,000; note is optional (up to 200 characters). Supply a unique idempotencyKey (8–200 characters) for each intended grant; reuse exactly that key and payload on retries, including across API and MCP, to avoid adding twice. Reusing a key for a different amount/note is refused. Returns the current customer-visible credits and history. Cannot subtract credits or change hidden allocation, package or billing settings. Requires an identified agency user with Clients page access and access to this client.
• Readget_client_portal_brandRead a client's portal branding: its logo, color, favicon and logo tone; the agency defaults; and the effective whole-bundle selection. Requires the same Clients page and client access as the UI.
• Writeupdate_client_portal_brandCustomize a client's portal logo, color, favicon and logo tone. This replaces the whole bundle, matching the UI. Set customized=false to clear all overrides and inherit agency defaults. Requires an identified agency user with access to this client.
• Readget_client_notificationsRead a client's effective portal-notification switches, whether it inherits agency defaults, and whether the current user may edit them. Returns supported client notification rows only, not operational notification plumbing.
• Writeupdate_client_notificationsChange a client's supported notification switches as an agency owner/admin. Partial config updates preserve unspecified switches; config=null resets the client to agency defaults. A client user or ordinary agency member cannot change these settings.
• Readlist_client_portal_usersList the client's portal users and invitation dates. This is a read-only operation and does not create legacy contact users.
• Writeadd_client_portal_userAdd a portal user by email and optionally send their invitation (default true). The first user becomes owner. If email delivery fails, the added user is retained and the result explains that an invitation needs resending.
• Writeupdate_client_portal_userEnable or disable a client's portal user, or transfer ownership with makePrimary=true. Matches the UI's row actions. Email and names cannot be changed here.
• Writeremove_client_portal_userRemove a client's portal user and expire their outstanding sign-in links. Transfer ownership first if the owner has other users.
• Writerevoke_client_portal_invitationsRevoke the client's outstanding invitation links and remove never-signed-in pending users. Accepted users remain. Returns the number of expired links and pending users removed.
• Readlist_portal_invite_templatesList this agency's reusable portal invitation emails, default first. Requires agency-wide client access because these templates are shared by all clients.
• Writecreate_portal_invite_templateSave a new reusable portal invitation email; it never edits an existing template. Supported invitation variables only. Optionally transfer the agency default to this template. Requires agency-wide client access.
• Writeset_default_portal_invite_templateMake an existing invitation template the agency default. It replaces the previous default; isDefault must be true. Requires agency-wide client access.
• Writedelete_portal_invite_templateDelete an agency invitation template. Deleting the default restores built-in invitation copy. Requires agency-wide client access.
• Writeimport_google_locationsImport an explicit Google selection into a client: selected fetchedListingIds (scope=ids), a folder (scope=folder), or the account (scope=account). Queues the same import as the UI. maxLocations explicitly permits partial import; capacity refusal, already-imported/in-progress counts and partial dispatch are returned without silently claiming success. notifyByEmail sends completion to the identified acting user. Browse cached locations first.
• Readget_client_google_snapshotRead the client's latest Google reporting snapshot and connection/sync status. Only the current GA4/Search Console/GBP selection and snapshots captured since connection are included. A pending snapshot is null. Does not trigger collection or refresh.
• Readget_client_locations_analyticsRead analytics summed across all locations of one client, for Google, Facebook or Bing. The UI's trailing reporting-lag trim, totals and any-location connection signal are preserved. days defaults to 30 (7–90).
• Readget_client_auditRead the client's audit history, including deleted and archived locations and portal users. Covers only the trigger-audited client, location and portal-user changes; posts/review replies are not captured. Filter by locationId, from/to (UTC dates or ISO timestamps, to exclusive), before cursor, and limit (1–100). Returns timezone and locations for filtering. Agency sessions only.
• Writepromote_location_to_clientMake a standalone location's hidden client into a named client. Preserves the same client identity and all its data, connections and access grants. Requires client-management permission and access to this client. An already-named client or duplicate name is refused.
• Readlist_publisher_setsList this agency's publisher sets — the named bundles of listing directories an agency sells, e.g. "Starter" (Google + Facebook only) or "Full Coverage". A client assigned to a set is listed ONLY on that set's sites: everything outside it disappears for the client and stops syncing. Returns each set's id, name, the siteIds it contains, how many clients are on it (clientCount), the `revision` you must pass back to update_publisher_set, and `adjustment` — the state of the background job that applies a set change to its clients' listings (up_to_date / in_progress / failed). Resolve a siteId to a directory name with list_sites. Read-only. You don't pass an agency — it comes from your credentials.
• Readget_publisher_setGet one publisher set by its id, with its directories resolved to names. Returns the set (id, name, revision, siteIds, clientCount, created/updated) plus `sites` — the display name and url for each siteId, so you can tell a person which directories the set actually covers. `unknownSiteIds` lists any site that is no longer selectable for this agency (deactivated, or dropped out of the agency's entitlement): those stay on the set and keep working, but cannot be re-added once removed. Pass `revision` back to update_publisher_set — it is how a concurrent edit is detected instead of silently overwritten. Read-only.
• Readget_client_publisher_setWhich publisher set a given client is on, and what that actually leaves the client listed on. Returns `publisherSet` (null when the client is on no set — meaning the agency's full entitlement applies), `effectiveSiteIds` — the sites the client really gets, i.e. the set narrowed by the agency's own entitlement; `null` there means unrestricted and an EMPTY ARRAY means no sites at all, which is a real answer, not a missing one — and `rollout`, the background job that applies the current set to this client's listings (pending/in progress/failed/completed, with the last error). Use this first when asked why a client is or isn't on some directory: a missing directory is usually the set, not a sync failure. Note a per-LOCATION exclusion can hide a site on top of this — see get_location_directories with includeOptedOut. Read-only.
• Writecreate_publisher_setCreate a new publisher set: a named bundle of listing directories the agency can then put clients on. Pass `name` (unique within the agency, case-insensitive) and `siteIds` — the numeric site ids from list_sites. An EMPTY siteIds array is allowed and means "exclude everything"; it is a real choice, not a shortcut for "all sites" — a client on an empty set is listed nowhere. A set can only contain directories the agency's own entitlement already includes: it narrows what the agency can offer, it can never widen it. Creating a set changes nothing on its own — no client is affected until assign_publisher_set puts one on it. Requires an identified agency user.
• Writeupdate_publisher_setRename a publisher set and/or replace the directories it covers. `siteIds` REPLACES the whole selection — it is not a delta, so send the full list you want (read the current one with get_publisher_set and add to or remove from it). You must pass the `revision` get_publisher_set returned: if someone else edited the set in the meantime the call is refused rather than overwriting them, and you re-read and re-apply. Editing an assigned set changes every client on it: a directory you remove disappears for those clients and stops syncing, a directory you add starts being worked on. That happens in the background — the response's `affectedClients` says how many clients were queued for it, and get_client_publisher_set reports where each one got to. Requires an identified agency user.
• Writedelete_publisher_setDelete a publisher set. Refused while any client is still on it — deleting it would silently hand those clients every directory again, which is the opposite of what the set was for. Move them off first with assign_publisher_set (to another set, or to none). Check `clientCount` from list_publisher_sets before calling. Requires an identified agency user.
• Writeassign_publisher_setPut one or more clients on a publisher set, or take them off it. Pass `clientIds` (from list_clients) and `publisherSetId`; OMIT publisherSetId, or pass null, to REMOVE the assignment — a client on no set falls back to the agency's full entitlement, i.e. it is listed on everything the agency can offer. This changes what those clients are listed on: directories the new set leaves out disappear for the client, drop out of their counts and scores, and stop syncing, while unsent listing work for them is canceled. Nothing is sent to any publisher and no connected account is touched — a live listing already on a directory's site stays up, and moving the client back restores the row rather than starting over. The listings are adjusted by a background job, so the effect is not instant: get_client_publisher_set reports how far it got. All or nothing: if any client id is not available to you, no client is changed at all. Up to 100 clients per call, and a client may not be named twice. Requires an identified agency user, who may only assign clients they themselves can access.