Clients API

A client is a company you bill and support — what some tools call a customer or account. Use this API to create and update clients, read them in bulk, reach their contacts and locations, and merge duplicate or acquired accounts.

Create a client

Only client_name and billing_cycle are required; contact details, address, payment terms, tax ID, and default currency are optional and can be filled in later. billing_cycle is one of weekly, bi-weekly, monthly, quarterly, semi-annually, or annually. Pass default_currency_code as a three-character ISO 4217 code (e.g. USD, EUR, GBP) to set the client's default billing currency; you can also set or change it later via PUT /api/v1/clients/{id}.

Pass an optional client_since date string in YYYY-MM-DD format to record when the MSP relationship began. This is independent of the record's created_at timestamp — useful when migrating clients whose relationship predates AlgaPSA. Omit it to leave it unset; it can be added or changed later via PUT /api/v1/clients/{id}.

curl https://algapsa.com/api/v1/clients \
  -H "X-API-Key: $ALGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Riverside Dental Group",
    "billing_cycle": "monthly",
    "email": "ap@riversidedental.example",
    "payment_terms": "net_30",
    "default_currency_code": "USD"
  }'

Contacts and locations

A client owns its contacts and locations. List them with GET /api/v1/clients/{id}/contacts and GET /api/v1/clients/{id}/locations, and add a site with POST /api/v1/clients/{id}/locations. Individual people are managed through the Contacts API.

Read clients

GET /api/v1/clients lists and filters; pass a client ID to GET /api/v1/clients/{id} for one record, or hit GET /api/v1/clients/stats for aggregate counts. A client is either a company or an individual — set client_type when you create one, and filter the list by it when you need just one kind.

Contact details from the default location

Both GET /api/v1/clients and GET /api/v1/clients/{id} include phone_no, email, and address in their responses. These fields are populated from the client's default active location, so you do not need to call the locations sub-resource just to display basic contact details. address is a single formatted string combining the location's address lines, city, state/province, postal code, and country, or null if the default location has no address set.

Merge clients

When a company is acquired or multiple client records represent the same entity, you can merge one client into another. The source client's billing profiles — including their invoices, billing cycles, payment methods, transactions, credits, and tax settings — are re-parented to the target client rather than copied, so the financial history stays intact. Work items such as tickets, projects, assets, and contacts are re-attributed to the target. The merge is permanent; the source client becomes a tombstone and can no longer be edited or billed.

Use POST /api/v1/clients/{id}/merge/preview (where {id} is the source client) to run a dry-run that returns the full plan and any blockers — such as the source already being merged, a parent-link cycle, or an invalid contract cutover date — without committing anything. Once the plan looks correct, call POST /api/v1/clients/{id}/merge with target_client_id in the request body to execute. Both endpoints require client:update and client:delete permissions. The execute endpoint is marked approvalRequired in the AI/MCP tool registry, so AI-driven callers will prompt for human confirmation before proceeding.

Billing profile contacts

After a merge, a client may carry multiple billing profiles — one per absorbed source. Each profile can have dedicated contacts designated as its managers. A contact who is a profile manager with can_view_profile_tickets: true gains read access to that profile's tickets from the client portal without affecting any other contact's visibility.

List the contacts assigned to a billing profile with GET /api/v1/clients/{id}/billing-profiles/{profileId}/contacts and replace the full list with PUT /api/v1/clients/{id}/billing-profiles/{profileId}/contacts. Clients that have only one billing profile do not require profile contact management and behave exactly as before.

Endpoints

Every endpoint links through to its full parameters, request and response schemas, and code samples.