Skip to content

Clients API

Client accounts and everything attached to them: profiles, groups, account credit, staff notes and files, authorized users and contacts, two-factor sign-in, passkeys and Google sign-in, ID documents and the affiliate program. Guest calls sign clients up and in. See Manage clients for the screens these calls stand behind.

Admin calls need Module access on the Client card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.

POST /api/admin/client/get_list

Lists client accounts, newest first, with filters.

Permission: View Client Details (client.view)

Parameter Type Description
search string A number finds the client by id or custom client ID (aid); 8 digits also find the client by Support PIN (the match is written to the activity log). Text matches company, first name, last name, full name or email.
id integer Client id or custom client ID (aid).
name string Part of the first or last name.
email string Part of the email.
company string Part of the company name.
status string active, suspended or canceled.
group_id integer Clients in this client group (any of their groups).
created_at string Clients created on this day.
date_from string Clients created at or after this date.
date_to string Clients created on or before this day (the whole day).
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has the profile fields id, email, email_approved, type, first_name, last_name, gender, birthday, phone_cc, phone, company, company_vat, company_number, address_1, address_2, city, state, postcode, country, currency, lang, timezone; the staff fields aid, group_id, role, auth_type, status, tax_exempt, notes, ip, referred_by, billing_email, created_at, updated_at, custom_1 to custom_20; balance (the credit the client can spend: account credit less what part-paid invoices hold) and group (the titles of all the client’s groups, comma separated, or null).

Example

Request parameters:

{
"search": "example.com",
"per_page": 1
}

result:

{
"pages": 12,
"page": 1,
"per_page": 1,
"total": 12,
"list": [
{
"id": 42,
"email": "jane@example.com",
"email_approved": true,
"type": "company",
"first_name": "Jane",
"last_name": "Doe",
"company": "Example Hosting",
"country": "US",
"currency": "USD",
"status": "active",
"group_id": 2,
"created_at": "2026-10-02 14:20:11",
"updated_at": "2026-11-15 08:03:40",
"balance": 25.5,
"group": "Resellers"
}
]
}

POST /api/admin/client/get_pairs

Returns client ids and names for a picker, newest clients first.

Permission: View Client Details (client.view)

Parameter Type Description
search string The same search as get_list, and its other filters (id, name, email, company, status, group_id, dates) work here too.
per_page integer How many pairs to return. Default 30.

Returns: An object of client id => "First Last (Company)" (the company part only when set).

Errors:

  • Invalid per page number, when per_page is not a number of 1 or more.
Example

Request parameters:

{
"search": "Jane"
}

result:

{
"42": "Jane Doe (Example Hosting)"
}

POST /api/admin/client/hosting_network

Tells whether the hosting network check is on, and whether this client may order from a hosting network anyway.

Permission: View Client Details (client.view)

Parameter Type Description
id integer The client id.

Returns: {on, allowed}: on is true while the hosting network check holds or blocks orders; allowed is true when staff let this client order from hosting networks (always false while the check is off).

POST /api/admin/client/get

Returns one client’s full profile, by id or by email.

Permission: View Client Details (client.view). The api_token field is included only for staff with Manage Client API Keys (client.manage_api_keys).

Parameter Type Description
id integer The client id. Give id or email.
email string The client’s sign-in email, used when no client has the id.

Returns: The client: every field of a get_list row, plus po_number (the purchase order number new invoices start with), balance (spendable credit), group and client_group ({id, title} of the first group), group_ids (every group the client is in), last_login_ip and last_login_at (the newest sign-in, or null), and api_token (see Permission).

Errors:

  • Client ID or email is required
  • Client not found
Example

Request parameters:

{
"id": 42
}

result:

{
"id": 42,
"email": "jane@example.com",
"email_approved": true,
"type": "company",
"first_name": "Jane",
"last_name": "Doe",
"company": "Example Hosting",
"country": "US",
"currency": "USD",
"lang": "en_US",
"timezone": "America/New_York",
"status": "active",
"tax_exempt": false,
"billing_email": "billing@example.com",
"po_number": null,
"balance": 25.5,
"group": "Resellers",
"client_group": {
"id": 2,
"title": "Resellers"
},
"group_ids": [
2
],
"created_at": "2026-10-02 14:20:11",
"last_login_ip": "203.0.113.10",
"last_login_at": "2026-11-16 18:44:02"
}

POST /api/admin/client/login

Signs the current session in to the client area as the client (Login as Client), as the account owner. No two-factor code or email PIN is asked.

Permission: Login as Client (client.impersonate_login)

Parameter Type Description
id integer, required The client id.
strip_admin_identity boolean Also sign the staff member out of the admin area in the same request. Default false.

Returns: {id, email, name, role} of the client.

Errors:

  • Client not found

The sign-in is written to the activity log.

POST /api/admin/client/create

Creates a client account and, by default, emails the client a welcome message with a link to set a password.

Permission: Create Clients (client.create)

Parameter Type Description
email string, required The sign-in email. Must not belong to another client.
first_name string, required First name.
password string The password; must meet the password strength rules. Without it the client gets a random one and sets their own from the welcome email.
send_welcome_email boolean Send the welcome email. Default true. With false a password is required.
status string active (default), suspended or canceled. The welcome email can only go to an active client.
last_name string Last name.
billing_email string A separate address for invoice emails. Empty for none.
group_id integer A client group.
group_ids array Several client groups (overrides group_id); the first is the main one.
type string individual or company.
company string Company name.
company_vat string VAT number. An EU VAT number is checked with VIES and can set the tax exemption.
company_number string Company registration number.
address_1 string Address line 1.
address_2 string Address line 2.
city string City.
state string State or region.
postcode string Postal code.
country string Two-letter country code, such as US. Default: the company’s default country.
phone_cc string Phone country code, such as 1.
phone string Phone number.
gender string male, female, nonbinary or other.
birthday string Date of birth, YYYY-MM-DD.
currency string The client’s currency code, such as USD.
lang string Language (locale) code, such as en_US, for the client’s emails.
timezone string IANA time zone, such as America/New_York.
notes string Notes for staff only.
aid string Custom client ID, such as the id in another billing system.
auth_type string Stored as given. Default empty.
created_at string The account’s creation date, for imports. Default now.
ip string The sign-up IP address to record.
custom_1 … custom_20 string The custom client fields.

Returns: The new client’s id.

Errors:

  • This email address is already registered.
  • A password is required when the welcome email is disabled.
  • Welcome email can only be sent for active clients.
  • Invalid country code: XX
  • Invalid locale code: xx
  • Invalid client group ID: x, or Client group not found
  • A password strength message when password is too weak

Fires onBeforeAdminClientCreate and onAfterAdminClientCreate. The welcome email includes the email confirmation link when the client settings require confirmation.

Example

Request parameters:

{
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe",
"company": "Example Hosting",
"country": "US",
"currency": "USD",
"group_ids": [
2
]
}

result:

42

POST /api/admin/client/privacy_anonymize

Anonymizes a client: names, email, address, phone, IP addresses, notes, ticket messages, sent emails and sign-in history are erased, and sign-in stops. Orders, invoices, payments and other money records stay.

Permission: Delete Clients (client.delete), and the privacy tools must be on (System → Settings → Clients → Privacy)

Parameter Type Description
id integer, required The client id.

Returns: true.

Errors:

  • The privacy tools are off (System → Settings → Clients → Privacy).
  • Client not found (code 404)
  • This client is anonymized already.
  • This client has N live services (active, pending or suspended). Cancel them first.
  • This client has N unpaid invoices. Settle or cancel them first.
  • This client has an affiliate payout request waiting. Pay or decline it first.

This cannot be undone. See Privacy tools.

POST /api/admin/client/delete

Deletes a client and everything kept about it: orders, invoices, tickets, account credit, emails, notes, files, ID documents, quotes, affiliate account and authorized users’ access.

Permission: Delete Clients (client.delete)

Parameter Type Description
id integer, required The client id.

Returns: true.

Errors:

  • Invalid client ID
  • Client not found

This cannot be undone. Fires onBeforeAdminClientDelete and onAfterAdminClientDelete. An authorized user left without any account is deleted too. To keep the money records, use privacy_anonymize instead.

POST /api/admin/client/update

Changes a client’s profile. Only the fields you send change.

Permission: Edit Client Profiles (client.edit_profile). Changing the sign-in email also needs Change Client Passwords (client.change_password).

Parameter Type Description
id integer, required The client id.
email string New sign-in email. A changed address becomes unconfirmed, and password reset links sent before stop working.
billing_email string Address for invoice emails; empty clears it.
first_name string First name.
last_name string Last name.
status string active, suspended or canceled. Leaving active ends the client’s sessions and clears the API token.
group_id integer Puts the client in this one group (also read as client_group_id); empty removes every group.
group_ids array The full list of the client’s groups (overrides group_id).
currency string The client’s currency. Refused once the client has invoices, orders, account credit or affiliate earnings.
email_approved boolean Marks the email confirmed or not (a changed email is always unconfirmed).
tax_exempt boolean Exempt the client from tax.
hosting_network_allowed boolean Let this client order from hosting networks while the hosting network check is on.
po_number string The purchase order number new invoices start with.
birthday string YYYY-MM-DD; empty or null clears it.
created_at string The account’s creation date; empty clears it.
type string individual or company.
company string Company name.
company_vat string VAT number; an EU VAT number is checked with VIES and can set the tax exemption.
company_number string Company registration number.
address_1 string Address line 1.
address_2 string Address line 2.
city string City.
state string State or region.
postcode string Postal code.
country string Two-letter country code.
phone_cc string Phone country code.
phone string Phone number.
gender string male, female, nonbinary or other.
lang string Language (locale) code.
timezone string IANA time zone; empty clears it.
notes string Notes for staff only.
aid string Custom client ID.
custom_1 … custom_20 string The custom client fields.

Returns: true.

Errors:

  • Client not found
  • This email address is already registered.
  • Invalid country code: XX
  • Invalid locale code: xx
  • Invalid timezone: x
  • Currency cannot be changed. Client already has invoices issued. (and the same for orders, account credit and affiliate earnings)
  • Client group not found

Fires onBeforeAdminClientUpdate and onAfterAdminClientUpdate.

Example

Request parameters:

{
"id": 42,
"company": "Example Hosting LLC",
"phone_cc": "1",
"phone": "5550100"
}

result:

true

POST /api/admin/client/change_password

Sets a new password for the client and signs the client out everywhere.

Permission: Change Client Passwords (client.change_password)

Parameter Type Description
id integer, required The client id.
password string, required The new password; must meet the password strength rules.
password_confirm string, required The same password again.

Returns: true.

Errors:

  • Passwords do not match.
  • Client not found

Fires onBeforeAdminClientPasswordChange and onAfterAdminClientPasswordChange.

POST /api/admin/client/balance_get_list

Lists account credit rows (additions and deductions), newest first.

Permission: Manage Client Balance (client.manage_balance)

Parameter Type Description
client_id integer Rows of one client.
id integer One row by id.
date_from string Rows created from this date.
date_to string Rows created up to and including this day.
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has id, description, amount (negative for a deduction), currency (the client’s) and created_at.

POST /api/admin/client/balance_delete

Removes one account credit row, which changes the client’s balance by its amount.

Permission: Manage Client Balance (client.manage_balance)

Parameter Type Description
id integer, required The id of the credit row (not the client id).

Returns: true.

Errors:

  • Balance line not found

POST /api/admin/client/balance_add_funds

Adds account credit to a client.

Permission: Manage Client Balance (client.manage_balance)

Parameter Type Description
id integer, required The client id.
amount number, required The amount, in the client’s currency.
description string, required What the client sees on the row.
type string A type label stored on the row. Default gift.
rel_id string The id of a related record, stored on the row.

Returns: true.

Errors:

  • Client not found
  • You must define the client’s currency before adding funds.
  • Funds amount is invalid
  • Funds description is invalid

A positive amount puts a notice in the client’s notification bell.

Example

Request parameters:

{
"id": 42,
"amount": 20,
"description": "Goodwill credit"
}

result:

true

POST /api/admin/client/summary

Returns the figures of the client page’s summary cards: invoices by status, services by type, yearly recurring amounts, renewals within 30 days, credit, open quotes and open tickets.

Permission: View Client Details (client.view), View invoices (invoice.view), View orders (order.view) and View support tickets (support.view)

Parameter Type Description
id integer, required The client id.

Returns: currency; recurring (service type => active services’ amount a year); renewing ({count, total} of active services expiring within 30 days); invoices (paid, unpaid, draft, cancelled, refunded, each {count, total}); gross_revenue (the paid total); credit_balance; services (type => {type, title, active, total}); addon_count; open_quotes; open_tickets. Amounts count only records in the client’s currency.

Errors:

  • Client not found

POST /api/admin/client/trust_score

Returns the client’s trust score out of 100, as the client page shows it. Nothing in ClientFence acts on it.

Permission: View Client Details (client.view) and View invoices (invoice.view)

Parameter Type Description
id integer, required The client id.

Returns: total (0 to 100); band (very_good 80+, good 60+, fair 40+, else watch); parts (on_time up to 40, since up to 20, services up to 15, paid up to 15, verified up to 10); deductions (fraud 20 when the fraud check ever held an order, refunds 5 per refunded invoice or reversed payment); counts (due, on_time, months, active, paid, email, id_document, refunded, reversed).

Errors:

  • Client not found

POST /api/admin/client/balance_deduct

Takes account credit away from a client.

Permission: Manage Client Balance (client.manage_balance)

Parameter Type Description
id integer, required The client id.
amount number, required The amount to take, above 0, in the client’s currency.
description string, required What the client sees on the row.

Returns: true.

Errors:

  • Client not found
  • Funds amount is invalid
  • Insufficient credit balance (more than the client has)
  • Funds description is invalid

POST /api/admin/client/close

Closes a client account: cancels the client’s active and suspended orders and sets the client to canceled.

Permission: Edit Client Profiles (client.edit_profile) and Manage orders (order.manage)

Parameter Type Description
id integer, required The client id.

Returns: {cancelled}: how many orders were cancelled.

Errors:

  • Client not found

Each order is cancelled as on its order page, with its subscription and add-ons. The client’s API token is cleared and the client’s sessions end.

POST /api/admin/client/note_get_list

Lists the staff notes on a client, pinned first, then newest first.

Permission: View Client Details (client.view)

Parameter Type Description
client_id integer, required The client id.

Returns: A list of notes: id, client_id, admin_id, note, pinned (1 or 0), created_at, updated_at, author (the staff member’s name).

POST /api/admin/client/note_create

Adds a staff note to a client.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer, required The client id.
note string, required The note text (up to 65,535 bytes).

Returns: The new note’s id.

Errors:

  • Client not found
  • Note is required
  • Note is too long

POST /api/admin/client/note_update

Changes a staff note’s text and whether it is pinned.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
id integer, required The note id.
note string, required The new text.
pinned integer, required 1 to pin the note at the top, 0 to unpin. Send a number: false counts as missing.

Returns: true.

Errors:

  • Note not found
  • Note is required
  • Note is too long

POST /api/admin/client/note_delete

Deletes a staff note.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
id integer, required The note id.

Returns: true.

Errors:

  • Note not found

POST /api/admin/client/balance_alert_get

Returns the client’s low balance alert, as the client page shows it.

Permission: View Client Details (client.view)

Parameter Type Description
id integer, required The client id.

Returns: null while low balance alerts are off in the settings; else {threshold}: the amount below which the client is emailed, or null when the client set none.

POST /api/admin/client/support_pin

Returns the client’s 8-digit Support PIN, making one the first time. Staff ask for it to confirm who they talk to.

Permission: View Client Details (client.view)

Parameter Type Description
id integer, required The client id.

Returns: The PIN, a string of 8 digits.

Errors:

  • Client not found

See Manage clients.

POST /api/admin/client/support_pin_new

Gives the client a new random Support PIN; the old one stops working.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
id integer, required The client id.

Returns: The new PIN, a string of 8 digits.

Errors:

  • Client not found

POST /api/admin/client/file_get_list

Lists the files staff attached to a client, newest first. Clients do not see them.

Permission: View Client Details (client.view)

Parameter Type Description
client_id integer, required The client id.

Returns: A list of files: id, client_id, admin_id, name, size (bytes), mime, created_at, author (the staff member’s name).

POST /api/admin/client/file_upload

Attaches a file to a client. Send it as a multipart form upload in the field file.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer, required The client id.
file mixed, required The uploaded file (multipart form field), smaller than 10 MB, of a type ticket attachments allow.

Returns: The saved file: client_id, admin_id, name, size, mime, created_at, id.

Errors:

  • Choose a file to attach.
  • Each file must be smaller than 10 MB.
  • This type of file cannot be attached. Allowed: …
  • Client not found

POST /api/admin/client/file_delete

Deletes a file attached to a client.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
id integer, required The file id.

Returns: true.

Errors:

  • File not found

POST /api/admin/client/id_document_list

Returns the client’s ID documents tab: whether ID documents are on and the documents the client sent, newest first.

Permission: View Client Details (client.view)

Parameter Type Description
client_id integer, required The client id.

Returns: {on, documents}. Each document has id, name, mime, size, status (waiting, approved, refused), reason, created_at, decided_at, has_file (false once the file was deleted after the keep period) and admin_name (who decided). documents is empty while the feature is off.

See ID documents.

POST /api/admin/client/id_document_approve

Approves the client’s waiting ID document. The client’s checkouts that wait only for it go on, and the client gets an email.

Permission: Edit Client Profiles (client.edit_profile) and Manage orders (order.manage)

Parameter Type Description
client_id integer, required The client id.

Returns: true.

Errors:

  • No ID document of this client is waiting for a decision.

Releasing a held checkout issues its invoice, as approving it in Orders → Waiting for review does.

POST /api/admin/client/id_document_refuse

Refuses the client’s waiting ID document. The client gets an email with the reason; held orders stay held.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer, required The client id.
reason string The reason the client reads, up to 255 characters. Needed: an empty reason is refused.

Returns: true.

Errors:

  • Enter the reason the client will read (up to 255 characters).
  • No ID document of this client is waiting for a decision.

POST /api/admin/client/id_document_settings_save

Saves the ID documents settings: who is asked for an ID document, how long files are kept and the text clients read.

Permission: Manage settings (client.manage_settings)

Parameter Type Description
id_documents string Who is asked: off (default), new (clients who sign up from now on), groups (clients in chosen groups) or held (clients with an order another check holds).
id_documents_groups array Client group ids, needed for groups.
id_documents_days integer Days the files are kept after the decision, 0 to 3650. Default 30.
id_documents_text string Text shown to clients, up to 5000 characters.

Returns: true.

Errors:

  • Choose who is asked for an ID document.
  • Choose at least one client group.
  • Enter how many days the files are kept after the decision (0 to 3650).
  • The text for clients can have up to 5000 characters.

POST /api/admin/client/batch_expire_password_reminders

Deletes client password reset requests older than 2 hours.

Permission: Delete Clients (client.delete)

No parameters.

Returns: true.

Cron already removes reset requests older than 15 minutes on every run.

POST /api/admin/client/login_history_get_list

Lists client sign-ins, newest first.

Permission: View Client Login History (client.view_login_history)

Parameter Type Description
client_id integer Sign-ins of one client.
search string Part of the client’s first name, last name or email, or the client id.
ip string Part of the IP address.
id integer One sign-in row by id.
date_from string From this day (00:00:00).
date_to string Up to this day (23:59:59).
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has id, ip, created_at, network, browser (sign-in details while they are kept, else null), user_email (the authorized user who signed in, or null for the owner) and client ({id, first_name, last_name, email}).

POST /api/admin/client/get_statuses

Counts clients by status.

Permission: View Client Details (client.view)

No parameters.

Returns: {total, active, suspended, canceled}.

Example

Request parameters:

{}

result:

{
"total": 57,
"active": 50,
"suspended": 3,
"canceled": 4
}

POST /api/admin/client/group_get_pairs

Returns the client groups as id and title pairs.

Permission: View Client Details (client.view)

No parameters.

Returns: An object of group id => title.

Example

Request parameters:

{}

result:

{
"1": "Default",
"2": "Resellers"
}

POST /api/admin/client/group_create

Creates a client group.

Permission: Manage Client Groups (client.manage_groups)

Parameter Type Description
title string, required The group’s name.

Returns: The new group’s id.

POST /api/admin/client/group_update

Renames a client group.

Permission: Manage Client Groups (client.manage_groups)

Parameter Type Description
id integer, required The group id.
title string The new name. Left out, the name stays.

Returns: true.

Errors:

  • Group not found

POST /api/admin/client/group_delete

Deletes a client group that has no clients in it.

Permission: Manage Client Groups (client.manage_groups)

Parameter Type Description
id integer, required The group id.

Returns: true.

Errors:

  • Group not found
  • Group has clients assigned. Please reassign them first.

POST /api/admin/client/group_get

Returns one client group.

Permission: Manage Client Groups (client.manage_groups)

Parameter Type Description
id integer, required The group id.

Returns: {id, title, created_at, updated_at}.

Errors:

  • Group not found

POST /api/admin/client/batch_delete

Deletes several clients, one after another, as delete does.

Permission: Bulk Delete Clients (client.bulk_delete) and Delete Clients (client.delete)

Parameter Type Description
ids array, required The client ids.

Returns: true.

Errors:

  • Invalid client ID
  • Client not found (stops at that id: the clients before it are already deleted)

This cannot be undone.

POST /api/admin/client/export_csv

Downloads every client as a CSV file (clients.csv). The answer is the file, not JSON.

Permission: View Client Details (client.view) and Export Clients (client.export)

Parameter Type Description
headers array The columns to export, from id, aid, client_group_id, role, auth_type, email, status, email_approved, tax_exempt, type, first_name, last_name, gender, birthday, phone_cc, phone, company, company_vat, company_number, address_1, address_2, city, state, postcode, country, notes, currency, lang, timezone, ip, referred_by, billing_email, po_number and custom_1 to custom_20, created_at and updated_at. Unknown names are dropped. Default: id, email, status, the names, phone, company and address fields, and currency.

Returns: A CSV file download.

POST /api/admin/client/user_list

Lists the authorized users of a client account: people who sign in to it with their own email and password.

Parameter Type Description
client_id integer The client id.

Returns: A list of users, by email: id, email, first_name, last_name, status (active or disabled), owner (full access, like the owner), permissions (a list of permission names), last_login_at (on this account), created_at (when access was given), twofactor, passkeys (count) and google (a Google account is linked).

See Client users. Permission names: profile, contacts, products, manageproducts, productsso, domains, managedomains, invoices, quotes, tickets, affiliates, emails, orders.

POST /api/admin/client/user_page

Returns what the client page’s Users tab shows: the account owner’s sign-in protection, the users, the pending invitations and the permissions offered.

Parameter Type Description
client_id integer The client id.

Returns: owner_twofactor, owner_passkeys (count), owner_google ({email, created_at, last_used_at} or null), owner_own_password (false for an account made by Google sign-up that has not chosen a password), users (as user_list), invites ({id, email, permissions, created_at, expires_at}; expired ones are removed), permissions ({name, label} of the permissions offered) and labels (permission name => label).

Errors:

  • Client not found. (code 404)

POST /api/admin/client/user_create

Gives a person access to a client account directly, without an invitation. A new email makes a new user; an existing user keeps their own details and password.

Permission: Edit Client Profiles (client.edit_profile) and Change Client Passwords (client.change_password), as for user_invite

Parameter Type Description
client_id integer The client id.
email string, required The user’s sign-in email. It cannot be an email a client account signs in with.
permissions array Permission names (see user_list), or a comma-separated string. Default none.
owner boolean Full access, like the account owner. Default false.
first_name string For a new user.
last_name string For a new user.
password string Needed for a new user; must meet the password strength rules.

Returns: The user’s id.

Errors:

  • Client not found. (code 404)
  • A client account already signs in with this email.
  • This user already has access to the account.
  • Unknown permission: x
  • A password strength message for a new user

POST /api/admin/client/user_invite

Invites a person by email to a client account with the given permissions. The person chooses a name and password from the link; an existing user accepts with their password. The link works for 7 days.

Permission: Edit Client Profiles (client.edit_profile) and Change Client Passwords (client.change_password)

Parameter Type Description
client_id integer The client id.
email string The person’s email. Needed: an empty or invalid email is refused.
permissions array Permission names (see user_list), or a comma-separated string. Default none.

Returns: true.

Errors:

  • Client not found. (code 404)
  • This is the account’s own email.
  • This user already has access to the account.
  • Too many invitations. Please try again later. (code 429; 20 invitation emails an hour per account)
  • Unknown permission: x

A new invitation to the same email replaces the old one. Written to the client’s activity log.

POST /api/admin/client/user_invite_resend

Sends a pending invitation again with a new link; the old link stops working.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer The client id.
id integer The invitation id.

Returns: true.

Errors:

  • Invitation not found. (code 404)
  • Too many invitations. Please try again later. (code 429)

POST /api/admin/client/user_invite_cancel

Cancels a pending invitation.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer The client id.
id integer The invitation id.

Returns: true.

Errors:

  • Invitation not found. (code 404)

POST /api/admin/client/user_update

Changes a user’s permissions and full access on one account, and the user’s status (which applies to sign-in on every account the user has).

Permission: Edit Client Profiles (client.edit_profile). Changing owner also needs Change Client Passwords (client.change_password).

Parameter Type Description
client_id integer The client id.
user_id integer The user id.
permissions array The new permission names; left out, they stay.
owner boolean Full access, like the account owner; left out, it stays.
status string active or disabled; left out, it stays.

Returns: true.

Errors:

  • User not found. (code 404)
  • Unknown status.
  • Unknown permission: x

POST /api/admin/client/user_remove

Removes a user’s access to an account. A user left without any account is deleted.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer The client id.
user_id integer The user id.

Returns: true.

Errors:

  • User not found. (code 404)

POST /api/admin/client/user_password_reset

Emails a user of the account a password reset link, valid for 60 minutes. Older links stop working.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer The client id.
user_id integer The user id.

Returns: true.

Errors:

  • User not found. (code 404)
  • This user is switched off: switch the user on first.

POST /api/admin/client/twofactor_disable

Switches off two-factor sign-in for the account owner, or for one user of the account, when they lost the phone and the backup code.

Permission: Edit Client Profiles (client.edit_profile) and Change Client Passwords (client.change_password)

Parameter Type Description
client_id integer The client id.
user_id integer A user of the account; left out, the account owner.

Returns: true.

Errors:

  • Client not found. (code 404)
  • User not found. (code 404)
  • Two-factor sign-in is not on.

Written to the activity log. See Recover access.

POST /api/admin/client/passkeys_remove

Removes every passkey of the account owner, or of one user of the account, when they lost the device.

Permission: Edit Client Profiles (client.edit_profile) and Change Client Passwords (client.change_password)

Parameter Type Description
client_id integer The client id.
user_id integer A user of the account; left out, the account owner.

Returns: true.

Errors:

  • Client not found. (code 404)
  • User not found. (code 404)
  • This login has no passkeys.

POST /api/admin/client/google_unlink

Removes the Google account linked to the account owner’s sign-in, or to one user’s.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer The client id.
user_id integer A user of the account; left out, the account owner.

Returns: true.

Errors:

  • Client not found. (code 404)
  • User not found. (code 404)
  • No Google account is linked.

An account made by Google sign-up may have no password of its own; the client then sets one with Forgot password.

POST /api/admin/client/signin_get

Returns the Google sign-in settings. The client secret is never returned.

Permission: Manage settings (client.manage_settings)

No parameters.

Returns: on, client_id, secret_saved, redirect_uri (the address to register with Google), terms_url, privacy_url, signup_open (client sign-up is open), mode (both, signin or signup), signup_blocked (what stops Google sign-up from making accounts: off, mode, signup, pages) and signup_preview (a store preview link can still sign up).

See Google sign-in.

POST /api/admin/client/signin_update

Saves the Google sign-in settings.

Permission: Manage settings (client.manage_settings)

Parameter Type Description
google_signin string 1 on, 0 off (default).
google_mode string both (sign-in and sign-up), signin (sign-in only) or signup (sign-up only). Left out, it stays.
google_client_id string The Google OAuth client ID (ends in .apps.googleusercontent.com). Needed to switch it on.
google_client_secret string The client secret; empty keeps the saved one.
google_terms_url string Your Terms address (http or https); needed for Google sign-up to make accounts.
google_privacy_url string Your Privacy Policy address; needed for Google sign-up to make accounts.

Returns: true.

Errors:

  • The client ID is a Google OAuth client ID (it ends in .apps.googleusercontent.com).
  • The client secret is not valid.
  • Google sign-in needs the client ID and the client secret.
  • Choose how Google sign-in is offered.
  • The Terms and Privacy Policy addresses are web addresses (https://…).

POST /api/admin/client/contact_page

Returns the client page’s Contacts tab: the account’s contacts (people who get copies of chosen emails but do not sign in) and the email kinds.

Parameter Type Description
client_id integer The client id.

Returns: contacts (oldest first: id, first_name, last_name, company, email, phone_cc, phone, address_1, address_2, city, state, postcode, country, tax_id, emails (list of kinds), created_at, updated_at), kinds ({name, label, allowed}: general, invoice, product, domain, support, affiliate) and max (50 contacts per account).

Errors:

  • Client not found (code 404)

See Contacts.

POST /api/admin/client/contact_save

Adds a contact to a client account, or changes one when id is given.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer The client id.
id integer The contact to change; left out, a new contact.
first_name string, required Up to 100 characters.
email string, required The contact’s email; unique within the account.
last_name string Up to 100 characters.
company string Up to 100 characters.
phone_cc string Phone country code, 1 to 4 digits.
phone string Phone number.
address_1 string Address line 1.
address_2 string Address line 2.
city string City.
state string State or region.
postcode string Postal code.
country string Country.
tax_id string Tax id.
emails array The email kinds the contact gets a copy of: general, invoice, product, domain, support, affiliate (or a comma-separated string). Every field you leave out is saved empty.

Returns: The contact’s id.

Errors:

  • Client not found (code 404)
  • Contact not found (code 404)
  • An account can have up to 50 contacts.
  • Enter the contact’s first name.
  • Enter the contact’s email.
  • This account already has a contact with this email.
  • The phone country code is not valid.
  • The … is too long (N characters at most).

Emails with sign-in links, codes or passwords are never copied to contacts. Written to the client’s activity log.

POST /api/admin/client/contact_delete

Removes a contact from a client account.

Permission: Edit Client Profiles (client.edit_profile)

Parameter Type Description
client_id integer The client id.
id integer The contact id.

Returns: true.

Errors:

  • Contact not found (code 404)

POST /api/admin/client/affiliate_get

Returns a client’s affiliate account with its link, counts and balances.

Permission: View Client Details (client.view)

Parameter Type Description
client_id integer The client id.

Returns: null when the client is not an affiliate; else id, code, link (the referral link), status (active, inactive), currency, commission_type and commission_amount (the affiliate’s own commission, or null for the defaults), onetime, visitors, signups, minimum (minimum payout), request (the open payout request {id, amount, currency, created_at} or null), can_request, created_at, and the balances pending, available, held (the signup bonus until a first commission clears), requested, paid_out.

See Affiliates.

Example

Request parameters:

{
"client_id": 42
}

result:

{
"id": 7,
"code": "a1b2c3d4e5f6",
"link": "https://billing.example.com/?aff=a1b2c3d4e5f6",
"status": "active",
"currency": "USD",
"commission_type": null,
"commission_amount": null,
"onetime": false,
"visitors": 120,
"signups": 4,
"minimum": 50,
"request": null,
"can_request": true,
"created_at": "2026-10-05 10:00:00",
"pending": 12.5,
"available": 64,
"held": 0,
"requested": 0,
"paid_out": 100
}

POST /api/admin/client/affiliate_settings

Returns the affiliate program settings.

Permission: View Client Details (client.view)

No parameters.

Returns: enabled, type (percentage or fixed), amount, onetime, bonus (signup bonus), minimum (minimum payout), clearing_days, cookie_days, signup_text, join (clients may join by themselves). Amounts are in the default currency.

POST /api/admin/client/affiliate_get_pairs

Finds active affiliates for a picker, such as an order’s Assign affiliate field.

Permission: View Client Details (client.view)

Parameter Type Description
search string Part of the name, company, email or affiliate code, or the client id.
per_page integer How many, 1 to 30. Default 10.

Returns: An object of affiliate id => "First Last (Company) · code".

POST /api/admin/client/affiliate_order

Returns the affiliate that referred an order.

Permission: View Client Details (client.view)

Parameter Type Description
order_id integer The order id.

Returns: null, or affiliate_id, source (cookie: the referral link, or staff: assigned by staff), created_at, client_id, code, status, first_name, last_name, company (the affiliate’s client).

POST /api/admin/client/affiliate_invoice_earned

Tells whether an invoice earned an affiliate commission that a refund can take back.

Permission: View Client Details (client.view)

Parameter Type Description
id integer The invoice id.

Returns: true or false.

POST /api/admin/client/affiliate_get_list

Lists affiliates with their visitors, signups and balances, newest first.

Permission: View Client Details (client.view)

Parameter Type Description
status string active or inactive.
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has id, client_id, code, status, created_at, first_name, last_name, company, email, currency, visitors, signups, pending, balance (cleared total), paid_out, available and requests (open payout requests).

POST /api/admin/client/affiliate_activate

Makes a client an affiliate, or activates an inactive affiliate account again. A new affiliate gets a random code and the signup bonus.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
client_id integer The client id.

Returns: true (also when the account is already active).

Errors:

  • Client not found
  • Currency rate for XXX is not configured.

A client without a currency gets the default currency.

POST /api/admin/client/affiliate_update

Changes an affiliate account’s status and its own commission.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
client_id integer The affiliate’s client id.
status string active or inactive.
commission_type string percentage or fixed; empty uses the program defaults.
commission_amount number The commission, 0 or more.
onetime boolean One-time: each referred order pays only its first commission.

Returns: true.

Errors:

  • This client is not an affiliate.
  • Unknown affiliate status.
  • Unknown commission type.
  • The commission amount must be a number of zero or more.

POST /api/admin/client/affiliate_referrals

Lists the orders an affiliate referred, newest first.

Permission: View Client Details (client.view)

Parameter Type Description
client_id integer The affiliate’s client id.
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has id, client_id (the referred client), client_order_id, source, created_at, title and status (the order’s), first_name, last_name, company (the referred client’s) and earned.

Errors:

  • This client is not an affiliate.

POST /api/admin/client/affiliate_entries

Lists an affiliate’s ledger: commissions, bonus, manual rows, reversals and payouts, newest first.

Permission: View Client Details (client.view)

Parameter Type Description
client_id integer The affiliate’s client id.
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has id, type (commission, bonus, manual, reversal, payout), status (pending, cleared, cancelled), amount, currency, note, clears_at, created_at, source_amount, source_currency, rate, client_id, client_order_id, invoice_id, reverses_id, payout_id, admin_id and hold_until.

Errors:

  • This client is not an affiliate.

POST /api/admin/client/affiliate_entry_add

Adds a manual row to an affiliate’s ledger. It counts as cleared at once.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
client_id integer The affiliate’s client id.
amount number Positive to add, negative to take away; not zero. In the affiliate’s currency.
note string Why (required, up to 255 characters).

Returns: The new ledger row’s id.

Errors:

  • This client is not an affiliate.
  • Enter an amount other than zero.
  • A note is required.

POST /api/admin/client/affiliate_commission_cancel

Cancels a commission that has not cleared yet.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
id integer The ledger row id of the commission.

Returns: true.

Errors:

  • Commission not found
  • Only a pending commission can be cancelled.

POST /api/admin/client/affiliate_payout_get_list

Lists affiliate payout requests, newest first.

Permission: View Client Details (client.view)

Parameter Type Description
status string requested, paid or declined.
client_id integer Requests of one affiliate’s client.
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has the request’s id, affiliate_id, amount, currency, status, details (how the affiliate asked to be paid), method, admin_id, processed_at, created_at, updated_at, and client_id, code, first_name, last_name, company, email.

POST /api/admin/client/affiliate_payout_pay

Pays a payout request: as account credit, or recorded as paid outside ClientFence. The affiliate gets an email.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
id integer The payout request id.
method string credit (adds the amount to the client’s account credit) or outside (you paid it another way). Required.

Returns: true.

Errors:

  • Choose how the payout was paid.
  • Payout request not found
  • This payout request was already handled.
  • The affiliate balance no longer covers this payout. Decline it or add a manual entry first.

POST /api/admin/client/affiliate_payout_decline

Declines a payout request; its amount is available to the affiliate again. The affiliate gets an email.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
id integer The payout request id.
note string A note for the affiliate’s email, up to 2000 characters.

Returns: true.

Errors:

  • Payout request not found
  • This payout request was already handled.

POST /api/admin/client/affiliate_assign

Credits an order to an affiliate, replacing any affiliate it had. Later paid invoices of the order earn the commission.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
order_id integer The order id.
affiliate_id integer The affiliate id (not the client id).

Returns: true.

Errors:

  • Order not found
  • Add-on and domain orders do not earn affiliate commissions.
  • Affiliate not found
  • An affiliate cannot be referred to its own orders.

POST /api/admin/client/affiliate_unassign

Removes the affiliate from an order. Commissions it already earned stay.

Permission: Manage Affiliates (client.manage_affiliates)

Parameter Type Description
order_id integer The order id.

Returns: true.

Errors:

  • This order has no affiliate.

POST /api/client/client/balance_get_list

Lists the signed-in client’s account credit rows (additions and deductions), newest first.

Parameter Type Description
date_from string Rows created from this date.
date_to string Rows created up to and including this day.
id integer One row by id.
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has id, description, amount (negative for a deduction), currency and created_at.

An authorized user needs the invoices permission.

POST /api/client/client/balance_get_total

Returns the credit the signed-in client can spend: account credit less what part-paid invoices hold.

No parameters.

Returns: A number, in the client’s currency.

An authorized user needs the invoices or the orders permission.

Example

Request parameters:

{}

result:

25.5

POST /api/client/client/is_taxable

Tells whether tax applies to the signed-in client: tax is on in the settings and the client is not tax exempt.

No parameters.

Returns: true or false.

POST /api/client/client/resend_email_verification

Emails the signed-in client a new link to confirm the account email, unless it is already confirmed.

No parameters.

Returns: true: the email is sent, or it is already confirmed (nothing is sent then).

Rate limited per address and per account. For the account owner and users with full access only.

POST /api/client/client/user_session

Describes the signed-in authorized user, so a theme can show the user’s name and hide what the permissions do not allow.

No parameters.

Returns: null for the account owner. For an authorized user: user ({id, email, first_name, last_name}), account ({id, name}), owner (full access), permissions (every permission for full access) and accounts ({id, name, current} of each active account the user can switch to).

See Client users.

POST /api/client/client/user_switch

Moves the signed-in authorized user to another account the user has access to.

Parameter Type Description
client_id integer The account (client id) to switch to.

Returns: true.

Errors:

  • Only authorized users can switch accounts. (code 403)
  • Account not found. (code 404)
  • Your account requires two-factor sign-in. Please sign in with your passkey. (code 403)

The session gets a new id. If the other account requires two-factor sign-in and the user has none, the client area asks the user to set it up first.

POST /api/client/client/users_get_list

Returns the Users page: the account’s authorized users, pending invitations and the permissions that can be given.

No parameters.

Returns: users (id, email, first_name, last_name, status, owner, permissions, last_login_at, created_at, twofactor, passkeys, google), invites ({id, email, permissions, created_at, expires_at}), permissions ({name, label}) and self (the signed-in user’s id, who cannot change their own access, or null for the owner).

For the account owner and users with full access only.

POST /api/client/client/users_invite

Invites a person by email to the account with the given permissions. The link works for 7 days.

Parameter Type Description
email string The person’s email. Needed: an empty or invalid email is refused.
permissions array Permission names: profile, contacts, products, manageproducts, productsso, domains, managedomains, invoices, quotes, tickets, affiliates, emails, orders (or a comma-separated string).

Returns: true.

Errors:

  • This is the account’s own email.
  • This user already has access to the account.
  • Too many invitations. Please try again later. (code 429; 20 an hour per account)
  • Unknown permission: x

For the account owner and users with full access only.

POST /api/client/client/users_invite_resend

Sends a pending invitation again with a new link; the old link stops working.

Parameter Type Description
id integer The invitation id.

Returns: true.

Errors:

  • Invitation not found. (code 404)
  • Too many invitations. Please try again later. (code 429)

For the account owner and users with full access only.

POST /api/client/client/users_invite_cancel

Cancels a pending invitation.

Parameter Type Description
id integer The invitation id.

Returns: true.

Errors:

  • Invitation not found. (code 404)

For the account owner and users with full access only.

POST /api/client/client/users_update

Changes a user’s permissions on the account. Full access and the user’s status stay as they are.

Parameter Type Description
user_id integer The user id.
permissions array The new permission names; left out, the user has none.

Returns: true.

Errors:

  • You cannot change your own access.
  • User not found. (code 404)
  • Unknown permission: x

For the account owner and users with full access only.

POST /api/client/client/users_remove

Removes a user’s access to the account. A user left without any account is deleted.

Parameter Type Description
user_id integer The user id.

Returns: true.

Errors:

  • You cannot change your own access.
  • User not found. (code 404)

For the account owner and users with full access only.

POST /api/client/client/contacts_get_list

Returns the Contacts page: the account’s contacts and the email kinds they can get copies of.

No parameters.

Returns: contacts (id, first_name, last_name, company, email, phone_cc, phone, address_1, address_2, city, state, postcode, country, tax_id, emails, created_at, updated_at), kinds ({name, label, allowed}; allowed is false for kinds the signed-in user’s permissions do not cover) and max (50).

An authorized user needs the contacts permission. See Contacts.

POST /api/client/client/contacts_save

Adds a contact, or changes one when id is given.

Parameter Type Description
id integer The contact to change; left out, a new contact.
first_name string, required Up to 100 characters.
email string, required Unique within the account.
last_name string Up to 100 characters.
company string Company.
phone_cc string Phone country code, 1 to 4 digits.
phone string Phone number.
address_1 string Address line 1.
address_2 string Address line 2.
city string City.
state string State or region.
postcode string Postal code.
country string Country.
tax_id string Tax id.
emails array Kinds of email the contact gets a copy of: general, invoice, product, domain, support, affiliate. Fields you leave out are saved empty.

Returns: The contact’s id.

Errors:

  • Contact not found (code 404)
  • An account can have up to 50 contacts.
  • Enter the contact’s first name.
  • Enter the contact’s email.
  • This account already has a contact with this email.
  • The phone country code is not valid.

An authorized user needs the contacts permission and sets only the kinds its permissions cover (general: profile, invoice: invoices, product: manageproducts, domain: domains, support: tickets, affiliate: affiliates); other kinds the contact had stay, unless the email changes.

POST /api/client/client/contacts_delete

Removes a contact.

Parameter Type Description
id integer The contact id.

Returns: true.

Errors:

  • Contact not found (code 404)

An authorized user needs the contacts permission.

POST /api/client/client/user_profile_update

Changes the signed-in authorized user’s own name.

Parameter Type Description
first_name string, required Up to 100 characters.
last_name string Up to 100 characters.

Returns: true.

Errors:

  • Only authorized users have this profile. (code 403)
  • Enter your first name.

POST /api/client/client/user_password_change

Changes the signed-in authorized user’s own password. The user’s other sessions end; this one stays.

Parameter Type Description
current_password string, required The current password.
new_password string, required The new password; must meet the password strength rules.
confirm_password string, required The new password again.

Returns: true.

Errors:

  • Only authorized users have this profile. (code 403)
  • The current password is not correct.
  • Passwords do not match.

Rate limited per address and per user.

POST /api/client/client/twofactor_status

Returns the two-factor sign-in state of the signed-in login (the owner’s, or an authorized user’s own).

No parameters.

Returns: enabled, backup (a backup code is left), enabled_at, required (the portal requires it and this session must set it up) and needs_password (an account made by Google sign-up must choose a password first).

See Two-factor sign-in.

POST /api/client/client/google_status

Returns the Google sign-in state of the signed-in login.

No parameters.

Returns: on (Google sign-in is offered), link ({email, created_at, last_used_at} of the linked Google account, or null), needs_password (an account made by Google sign-up has no password of its own yet) and error (the last Google error, given once, or null).

POST /api/client/client/google_link

Starts linking a Google account to the signed-in login. Send the browser to the returned address; Google sends it back to the portal.

Parameter Type Description
password string, required The login’s password.

Returns: {url}: the Google page to open.

Errors:

  • Google sign-in is not available.
  • The password is not correct.

Rate limited per address and per login.

POST /api/client/client/google_profile_update

For an account made by Google sign-up: saves the profile fields the portal requires that Google did not give (asked on the Google profile page before the client area opens).

Parameter Type Description
last_name, company, phone, birthday, gender, address_1, address_2, city, state, postcode, country, custom_1 … custom_20 string Each field that is required at sign-up and still empty must be filled.
phone_cc string Phone country code, saved with phone.
password string In Sign-up only mode, the password the account chooses.
password_confirm string The password again.

Returns: true (also when nothing is missing).

Errors:

  • Please fill in every field.
  • Passwords do not match.

For the account owner only: authorized users, even with full access, cannot call it.

POST /api/client/client/google_password

For an account made by Google sign-up: chooses its first password, after which Google can be unlinked.

Parameter Type Description
password string, required The new password; must meet the password strength rules.
password_confirm string, required The same password again.

Returns: true.

Errors:

  • Your account already has a password. You can change it on your profile page.
  • Passwords do not match.

For the account owner only: authorized users, even with full access, cannot call it.

POST /api/client/client/google_unlink

Removes the Google account linked to the signed-in login. The password still signs in.

No parameters.

Returns: true.

Errors:

  • You sign in with Google only, so Google cannot be unlinked yet. Choose a password first, then unlink Google.
  • No Google account is linked.

POST /api/client/client/twofactor_setup

Starts setting up two-factor sign-in: a new secret for the authenticator app, kept in the session for 15 minutes until twofactor_enable.

No parameters.

Returns: {secret, uri}: the secret in groups of 4 characters for manual entry, and the otpauth:// address for a QR code.

Errors:

  • Two-factor sign-in is already on.

POST /api/client/client/twofactor_enable

Turns two-factor sign-in on with a code from the app for the secret of twofactor_setup. The login gets an email about it.

Parameter Type Description
code string, required The 6-digit code from the app.
password string, required The login’s password.

Returns: {backup_code}: shown once; it signs in once when the phone is lost.

Errors:

  • The setup has expired. Please start again.
  • The password is not correct.
  • The code is not correct. Check the time on your phone and try the newest code.

POST /api/client/client/twofactor_disable

Turns two-factor sign-in off.

Parameter Type Description
password string, required The login’s password.
code string, required A code from the app, or the backup code.

Returns: true.

Errors:

  • Two-factor sign-in is not on.
  • The password is not correct.
  • The code is not correct.

If the portal requires two-factor sign-in of the account, the client area then asks to set it up again.

POST /api/client/client/twofactor_backup

Makes a new backup code; the old one stops working.

Parameter Type Description
password string, required The login’s password.

Returns: {backup_code}.

Errors:

  • Two-factor sign-in is not on.
  • The password is not correct.

POST /api/client/client/passkey_list

Lists the passkeys of the signed-in login.

No parameters.

Returns: {on, passkeys}: on is false (and the list empty) while passkeys are off for clients; each passkey has id, name, created_at, last_used_at.

POST /api/client/client/passkey_options

Returns the options for the browser’s “create a passkey” prompt (navigator.credentials.create()).

Parameter Type Description
password string The login’s password. Not needed within 10 minutes of a sign-in that offered a passkey.

Returns: challenge, rp ({id, name}), user ({id, name, displayName}), pubKeyCredParams, authenticatorSelection, attestation (none), excludeCredentials and timeout (ms). Binary values are base64url strings.

Errors:

  • Passkeys are not on.
  • The password is not correct.

POST /api/client/client/passkey_add

Saves the passkey the browser made for passkey_options. The login gets an email about it.

Parameter Type Description
id string, required The credential id (base64url).
clientDataJSON string, required From the browser’s answer (base64url).
authenticatorData string, required From the browser’s answer (base64url).
publicKey string, required The key from getPublicKey() (base64url).
publicKeyAlgorithm integer, required -7 (ES256) or -257 (RS256).

Returns: {id, name}: the passkey, named after the browser.

Errors:

  • The passkey request has expired. Please try again.
  • This browser cannot create a passkey. Please update it, or use another browser.
  • This passkey uses a kind of key that cannot be used here. Please try another one.
  • This passkey is already saved.

POST /api/client/client/passkey_rename

Renames one of the signed-in login’s passkeys.

Parameter Type Description
id integer The passkey id.
name string, required The new name, up to 100 characters.

Returns: true

Errors:

  • Enter a name for the passkey.
  • Passkey not found. (code 404)

POST /api/client/client/passkey_remove

Removes one of the signed-in login’s passkeys.

Parameter Type Description
id integer The passkey id.
password string, required The login’s password.

Returns: true.

Errors:

  • The password is not correct.
  • Passkey not found. (code 404)

POST /api/client/client/passkey_offer

Tells the layout whether to show the “Sign in faster next time” passkey card: true once, on the first page after a sign-in that offered a passkey.

No parameters.

Returns: true or false.

POST /api/client/client/privacy_status

Returns the Privacy tab of the profile: which privacy tools are on and whether the client gets marketing email.

No parameters.

Returns: {tools, optout, marketing}: tools (data download and deletion request are on), optout (clients may turn marketing email off) and marketing (this client gets marketing email).

For the account owner and users with full access only. See Privacy tools.

POST /api/client/client/privacy_marketing_set

Turns marketing email (Mass Mailer) on or off for the signed-in client.

Parameter Type Description
marketing boolean 1 to get marketing email (default), 0 to stop it.

Returns: true.

Errors:

  • Marketing email settings are not available. (the opt-out is off in the settings)

For the account owner and users with full access only. Service email (invoices, tickets, sign-in) always goes.

POST /api/client/client/balance_alert_get

Returns the account’s low balance alert, shown on the Wallet page.

No parameters.

Returns: null while staff have low balance alerts off; else {threshold}: the amount, or null when the alert is off.

An authorized user needs the invoices permission.

POST /api/client/client/balance_alert_save

Turns the account’s low balance alert on below an amount, or off. The client gets one email when the balance falls below it.

Parameter Type Description
enabled boolean 1 on, 0 off. Default off.
amount number With enabled: the amount, above 0, in the account’s currency.

Returns: true.

Errors:

  • Low balance alerts are not available.
  • Enter an amount above 0 and below 1,000,000,000.

An authorized user needs the invoices permission. Saving again re-arms the alert.

POST /api/client/client/support_pin

Returns the account’s Support PIN, which staff ask for to confirm who they talk to.

No parameters.

Returns: The PIN, a string of 8 digits.

POST /api/client/client/support_pin_new

Makes a new random Support PIN; the old one stops working.

No parameters.

Returns: The new PIN.

An authorized user needs the profile permission.

POST /api/client/client/affiliate_get

Returns the Affiliates page: whether the program is on, whether the client may join, and the client’s affiliate account.

No parameters.

Returns: enabled, join (the client may join by themselves), signup_text, cookie_days, and affiliate: null before the client joins (or while the program is off), else the account as staff affiliate_get returns it (link, status, commission, counts and balances).

An authorized user needs the affiliates permission. See Affiliates.

POST /api/client/client/affiliate_join

Joins the affiliate program: the client gets an affiliate code and link, and the signup bonus if one is set.

No parameters.

Returns: true (also when already a member).

Errors:

  • The affiliate program is not open for sign-ups.
  • Your affiliate account is not active. Please contact us. (staff turned it off)

For the account owner and users with full access only.

POST /api/client/client/affiliate_referrals

Lists the orders the affiliate referred, newest first. It never shows who ordered.

Parameter Type Description
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has created_at, product, status (the order’s) and earned.

Errors:

  • The affiliate program is not available. (the program is off, or the client is not an affiliate)

An authorized user needs the affiliates permission.

POST /api/client/client/affiliate_entries

Lists the affiliate’s ledger, newest first.

Parameter Type Description
page integer Page number, from 1. Default 1.
per_page integer Rows per page, 1 to 500. Default 100.

Returns: A paged list. Each row has id, type (commission, bonus, manual, reversal, payout), status (pending, cleared, cancelled), amount, currency, note, clears_at and created_at.

Errors:

  • The affiliate program is not available.

An authorized user needs the affiliates permission.

POST /api/client/client/affiliate_payout_request

Asks for a payout of affiliate earnings. One request can be open at a time; staff pay it or decline it.

Parameter Type Description
amount number, required At least the minimum payout and at most the available balance.
details string, required How to pay you, up to 2000 characters.

Returns: The payout request’s id.

Errors:

  • The affiliate program is not available.
  • Your affiliate account is not active.
  • Enter the amount to pay out.
  • Tell us how to pay you (payout details).
  • The payout details are too long.
  • Your payout request is already waiting.
  • The minimum payout is X.
  • You can ask for at most X.

For the account owner and users with full access only. Staff with Manage Affiliates get an email.

POST /api/client/client/id_document_status

Returns the account’s ID document state, as the dashboard and order banners show it.

No parameters.

Returns: on, needed (upload one now), required, latest ({status, reason, created_at, decided_at} of the last one sent, or null), text (what staff wrote for clients), held (ids of orders waiting for it) and max_mb (10; not present while the feature is off).

Every authorized user may read it. See ID documents.

POST /api/client/client/id_document_send

Sends an ID document for staff to check: the front and, if it has one, the back, as a multipart form upload.

Parameter Type Description
front mixed, required The front, a JPG, PNG, WebP or PDF file smaller than 10 MB (multipart form field).
back mixed The back, same rules.

Returns: true.

Errors:

  • No ID document is needed for your account.
  • Your ID document is being checked. We will email you when it is done.
  • Choose the front of your ID document, and its back if it has one.
  • You sent several files in the last hour. Please try again later. (5 files an hour)
  • Each file must be smaller than 10 MB.
  • The file must be a JPG, PNG or WebP image or a PDF.

For the account owner and users with full access only. Staff get a notification. The files are stored encrypted.

POST /api/client/client/privacy_request_deletion

Asks staff to delete the account: opens a ticket in the first help desk, or returns the open one.

No parameters.

Returns: The ticket id.

Errors:

  • Account deletion requests are not available. Please open a ticket. (the privacy tools are off)
  • Your request could not be sent: there is no support desk. Please contact us.

For the account owner and users with full access only.

POST /api/guest/client/create

Signs up a new client account and, by default, signs it in.

Parameter Type Description
email string, required The sign-in email.
first_name string, required First name.
password string, required Must meet the password strength rules.
password_confirm string, required The same password again.
last_name string Last name.
type, company, company_vat, company_number, address_1, address_2, city, state, postcode, country, phone_cc, phone, gender, birthday string Profile fields, as in the admin create. Fields in the settings’ required list must be filled.
lang string Language code; default the language of the page.
timezone string IANA time zone.
custom_1 … custom_20 string Custom fields; required active ones must be filled.
g-recaptcha-response string The CAPTCHA answer, when a CAPTCHA is on.

Returns: true. The same answer comes back when the email already has an account (nothing is created then), so the call never reveals which emails are registered.

Errors:

  • New registrations are temporarily disabled
  • Passwords do not match.
  • Field X cannot be empty
  • You have to complete the CAPTCHA to continue
  • Invalid country code: XX

Needs the browser session’s CSRF token, a POST and a request from your billing site (see Authentication). Rate limited per address and per email. Sends the email confirmation when the settings require it. Fires onBeforeClientSignUp and onAfterClientSignUp. notes and aid are ignored here.

POST /api/guest/client/login

Signs a client in with email and password. An authorized user signs in the same way, to the account they used last.

Parameter Type Description
email string, required The sign-in email.
password string, required The password.
g-recaptcha-response string The CAPTCHA answer, when a CAPTCHA is on for the sign-in.

Returns: {id, email, name, role} when signed in; or {clientfence_twofactor: true} when the sign-in waits for a second step (the code from the app: twofactor_verify; or the email PIN: signin_pin).

Errors:

  • Please check your login details. (code 401)
  • Your account requires two-factor sign-in. Please sign in with your passkey. (code 403)

Needs the browser session’s CSRF token, a POST and a request from your billing site. Sign-in limit: 10 an hour per address. Fires onBeforeClientLogin, onAfterClientLogin and, on failure, onEventClientLoginFailed.

Example

Request parameters:

{
"email": "jane@example.com",
"password": "correct horse battery staple"
}

result:

{
"id": 42,
"email": "jane@example.com",
"name": "Jane Doe",
"role": "client"
}

POST /api/guest/client/reset_password

Emails a password reset link to a client or an authorized user with this email.

Parameter Type Description
email string, required The sign-in email.
g-recaptcha-response string The CAPTCHA answer, when a CAPTCHA is on.

Returns: true, whether or not the email has an account.

Errors:

  • You have to complete the CAPTCHA to continue

Rate limited per address and per email (over the limit nothing is sent, and the answer is still true). A client’s link works for 15 minutes; an authorized user’s for 60.

POST /api/guest/client/update_password

Sets a client’s new password from a reset link and signs the client out everywhere.

Parameter Type Description
hash string, required The code from the reset link.
password string, required The new password; must meet the password strength rules.
password_confirm string, required The same password again.

Returns: true.

Errors:

  • The link has expired or you have already reset your password.
  • Passwords do not match.

The client gets an email that the password changed. Fires onBeforeClientProfilePasswordReset and onAfterClientProfilePasswordReset. Authorized users use user_password_reset.

POST /api/guest/client/required

Lists the profile fields the sign-up form requires (Client settings).

No parameters.

Returns: A list of field names, such as ["last_name", "country"].

POST /api/guest/client/custom_fields

Returns the custom client fields, sorted by title.

No parameters.

Returns: An object of field name (custom_1 to custom_20) => {title, active, required} and any other saved settings of the field.

POST /api/guest/client/is_email_validation_required

Tells whether new clients must confirm their email.

No parameters.

Returns: true or false.

POST /api/guest/client/user_password_reset

Sets an authorized user’s new password from a reset link. The user is signed out everywhere.

Parameter Type Description
token string, required The token from the reset link.
password string, required Must meet the password strength rules.
password_confirm string, required The same password again.

Returns: true.

Errors:

  • The link has expired or you have already reset your password.
  • Passwords do not match.

Rate limited per address.

POST /api/guest/client/user_invite_accept

Accepts an invitation to a client account and signs the user in to it. An existing user confirms with their password; a new user chooses a name and password.

Parameter Type Description
token string, required The token from the invitation link.
password string, required An existing user’s password, or a new user’s chosen password.
password_confirm string A new user’s password again.
first_name string A new user’s first name (required for a new user).
last_name string A new user’s last name.

Returns: true when signed in; {clientfence_twofactor: true} when the user has two-factor sign-in and must enter the code (twofactor_verify).

Errors:

  • This invitation has expired or was already used.
  • Please check your login details. (code 401)
  • This email already signs in to a client account. Ask the account owner to invite another address.
  • Enter your first name.
  • Passwords do not match.

Needs the browser session’s CSRF token, a POST and a request from your billing site. Rate limited per address.

POST /api/guest/client/twofactor_verify

Finishes a sign-in that waits for a two-factor code.

Parameter Type Description
code string, required The 6-digit code from the app, or the backup code (which then stops working).

Returns: {backup_used}: true when the backup code was used.

Errors:

  • Your sign-in has expired. Please sign in again. (code 401)
  • The code is not correct.
  • Too many wrong codes. Please sign in again. (code 401; after 5 wrong codes)
  • Too many wrong codes. Please try again later. (code 429)

Needs the browser session’s CSRF token, a POST and a request from your billing site. The waiting sign-in lasts 5 minutes.

POST /api/guest/client/signin_pin

Finishes a sign-in that waits for the email PIN (sign-in security).

Parameter Type Description
pin string, required The PIN from the email.
trust boolean Trust this browser for 30 days, so it is not asked again.

Returns: true.

Errors:

  • Your sign-in has expired. Please sign in again. (code 401)
  • The PIN is not correct.
  • Too many wrong PINs. Please try again later. (code 429)
  • Too many wrong PINs. Please sign in again. (code 401)
  • Please check your login details. (code 401)

Needs the browser session’s CSRF token, a POST and a request from your billing site. See Sign-in security.

POST /api/guest/client/passkey_on

Tells whether the client sign-in page offers passkey sign-in.

No parameters.

Returns: true or false.

POST /api/guest/client/passkey_signin_options

Returns the options for the browser’s passkey prompt on the sign-in page (navigator.credentials.get()).

No parameters.

Returns: {challenge, rpId, userVerification, timeout}; the challenge is base64url and works once, for 5 minutes.

Errors:

  • Passkey sign-in is not on.

POST /api/guest/client/passkey_signin

Signs in with a passkey, instead of the password and the second step.

Parameter Type Description
id string, required The credential id (base64url).
clientDataJSON string, required From the browser’s answer (base64url).
authenticatorData string, required From the browser’s answer (base64url).
signature string, required From the browser’s answer (base64url).
userHandle string From the browser’s answer (base64url).

Returns: true.

Errors:

  • Passkey sign-in is not on.
  • This passkey is not set up for this sign-in. Please sign in with your password.
  • Please check your login details. (code 401)

Needs the browser session’s CSRF token, a POST and a request from your billing site. Sign-in limit: 10 an hour per address.

POST /api/guest/client/signin_pin_resend

Emails a new PIN for the sign-in waiting for one; the old PIN stops working.

No parameters.

Returns: {email, resend_in, minutes, trust_days}: the masked email, seconds until another resend, how long the PIN works (10 minutes) and the trust period (30 days).

Errors:

  • Your sign-in has expired. Please sign in again. (code 401)
  • Please wait a minute before asking for a new PIN. (code 429)
  • Too many PINs for this sign-in. Please sign in again later. (code 429; 5 per sign-in)

POST /api/guest/client/google_button

Returns what the Google buttons show on the sign-in and sign-up pages.

No parameters.

Returns: on (the sign-in page shows the button), signup (Google sign-up makes accounts), terms_url and privacy_url (when signup, else null) and error (the message of the last Google sign-in that failed, given once, or null).

See Google sign-in.

POST /api/guest/client/google_on

Tells whether existing logins can sign in with Google (Google sign-in is on and not Sign-up only).

No parameters.

Returns: true or false.

POST /api/guest/client/affiliate_on

Tells whether the affiliate program is on.

No parameters.

Returns: true or false.