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.
Admin calls
Section titled “Admin calls”get_list
Section titled “get_list”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, inactive, 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" } ]}get_pairs
Section titled “get_pairs”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_pageis not a number of 1 or more.
Example
Request parameters:
{ "search": "Jane"}result:
{ "42": "Jane Doe (Example Hosting)"}hosting_network
Section titled “hosting_network”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), the client options overdue_notices, separate_invoices, auto_charge, allow_sso, status_update and marketing, google_only (linked to Google and no password of their own), 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.
create
Section titled “create”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), inactive, suspended or canceled. The welcome email can only go to an active or inactive 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
passwordis 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:
42privacy_anonymize
Section titled “privacy_anonymize”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.
delete
Section titled “delete”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.
update
Section titled “update”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, inactive, suspended or canceled. inactive works as active; suspended or canceled 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. |
overdue_notices |
boolean | Overdue Notices: 0 sends no payment reminders after the due date. See Client options. |
separate_invoices |
boolean | Separate Invoices: 1 renews each service on its own invoice. |
auto_charge |
boolean | Automatic payments; 0 is Disable CC Processing on. |
status_update |
boolean | Status Update: 0 keeps the automatic status update off this client. |
allow_sso |
boolean | Allow Single Sign-On: 0 stops Google sign-in for the account owner. |
marketing |
boolean | Marketing email: 0 opts the client out of marketing Mass Mail messages, 1 removes the opt-out. With marketing_shown (the value shown before the change), the opt-out changes only when marketing differs from it. |
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:
truechange_password
Section titled “change_password”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.
balance_get_list
Section titled “balance_get_list”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.
balance_delete
Section titled “balance_delete”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
balance_add_funds
Section titled “balance_add_funds”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. A negative amount removes credit, up to the credit the client can spend (the figure the client page shows; part payments kept for an unpaid invoice do not count). |
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
- The client has
credit. You cannot remove more than that.
A positive amount puts a notice in the client’s notification bell.
Example
Request parameters:
{ "id": 42, "amount": 20, "description": "Goodwill credit"}result:
truesummary
Section titled “summary”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
trust_score
Section titled “trust_score”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
balance_deduct
Section titled “balance_deduct”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.
note_get_list
Section titled “note_get_list”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).
note_create
Section titled “note_create”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
note_update
Section titled “note_update”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
note_delete
Section titled “note_delete”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
balance_alert_get
Section titled “balance_alert_get”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.
support_pin
Section titled “support_pin”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.
support_pin_new
Section titled “support_pin_new”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
file_get_list
Section titled “file_get_list”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).
file_upload
Section titled “file_upload”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
file_delete
Section titled “file_delete”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
id_document_list
Section titled “id_document_list”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.
id_document_approve
Section titled “id_document_approve”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.
id_document_refuse
Section titled “id_document_refuse”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.
id_document_settings_save
Section titled “id_document_settings_save”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.
batch_expire_password_reminders
Section titled “batch_expire_password_reminders”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.
login_history_get_list
Section titled “login_history_get_list”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}).
get_statuses
Section titled “get_statuses”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}group_get_pairs
Section titled “group_get_pairs”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"}group_create
Section titled “group_create”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.
group_update
Section titled “group_update”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
group_delete
Section titled “group_delete”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.
group_get
Section titled “group_get”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
batch_delete
Section titled “batch_delete”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.
export_csv
Section titled “export_csv”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.
user_list
Section titled “user_list”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.
user_page
Section titled “user_page”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)
user_create
Section titled “user_create”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
user_invite
Section titled “user_invite”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.
user_invite_resend
Section titled “user_invite_resend”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)
user_invite_cancel
Section titled “user_invite_cancel”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)
user_update
Section titled “user_update”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
user_remove
Section titled “user_remove”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)
user_password_reset
Section titled “user_password_reset”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.
twofactor_disable
Section titled “twofactor_disable”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.
passkeys_remove
Section titled “passkeys_remove”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.
google_unlink
Section titled “google_unlink”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.
signin_get
Section titled “signin_get”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.
signin_update
Section titled “signin_update”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://…).
contact_page
Section titled “contact_page”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.
contact_save
Section titled “contact_save”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.
contact_delete
Section titled “contact_delete”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)
affiliate_get
Section titled “affiliate_get”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}affiliate_settings
Section titled “affiliate_settings”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.
affiliate_get_pairs
Section titled “affiliate_get_pairs”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".
affiliate_order
Section titled “affiliate_order”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).
affiliate_invoice_earned
Section titled “affiliate_invoice_earned”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.
affiliate_get_list
Section titled “affiliate_get_list”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).
affiliate_activate
Section titled “affiliate_activate”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.
affiliate_update
Section titled “affiliate_update”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.
affiliate_referrals
Section titled “affiliate_referrals”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.
affiliate_entries
Section titled “affiliate_entries”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.
affiliate_entry_add
Section titled “affiliate_entry_add”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.
affiliate_commission_cancel
Section titled “affiliate_commission_cancel”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.
affiliate_payout_get_list
Section titled “affiliate_payout_get_list”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.
affiliate_payout_pay
Section titled “affiliate_payout_pay”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.
affiliate_payout_decline
Section titled “affiliate_payout_decline”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.
affiliate_assign
Section titled “affiliate_assign”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.
affiliate_unassign
Section titled “affiliate_unassign”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.
Client calls
Section titled “Client calls”balance_get_list (client)
Section titled “balance_get_list (client)”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.
balance_get_total (client)
Section titled “balance_get_total (client)”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.5is_taxable (client)
Section titled “is_taxable (client)”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.
resend_email_verification (client)
Section titled “resend_email_verification (client)”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.
user_session (client)
Section titled “user_session (client)”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.
user_switch (client)
Section titled “user_switch (client)”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.
users_get_list (client)
Section titled “users_get_list (client)”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.
users_invite (client)
Section titled “users_invite (client)”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.
users_invite_resend (client)
Section titled “users_invite_resend (client)”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.
users_invite_cancel (client)
Section titled “users_invite_cancel (client)”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.
users_update (client)
Section titled “users_update (client)”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.
users_remove (client)
Section titled “users_remove (client)”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.
contacts_get_list (client)
Section titled “contacts_get_list (client)”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.
contacts_save (client)
Section titled “contacts_save (client)”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.
contacts_delete (client)
Section titled “contacts_delete (client)”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.
user_profile_update (client)
Section titled “user_profile_update (client)”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.
user_password_change (client)
Section titled “user_password_change (client)”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.
twofactor_status (client)
Section titled “twofactor_status (client)”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.
google_status (client)
Section titled “google_status (client)”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).
google_link (client)
Section titled “google_link (client)”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.
google_profile_update (client)
Section titled “google_profile_update (client)”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.
google_password (client)
Section titled “google_password (client)”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.
google_unlink (client)
Section titled “google_unlink (client)”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.
twofactor_setup (client)
Section titled “twofactor_setup (client)”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.
twofactor_enable (client)
Section titled “twofactor_enable (client)”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.
twofactor_disable (client)
Section titled “twofactor_disable (client)”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.
twofactor_backup (client)
Section titled “twofactor_backup (client)”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.
passkey_list (client)
Section titled “passkey_list (client)”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.
passkey_options (client)
Section titled “passkey_options (client)”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.
passkey_add (client)
Section titled “passkey_add (client)”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.
passkey_rename (client)
Section titled “passkey_rename (client)”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)
passkey_remove (client)
Section titled “passkey_remove (client)”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)
passkey_offer (client)
Section titled “passkey_offer (client)”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.
privacy_status (client)
Section titled “privacy_status (client)”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.
privacy_marketing_set (client)
Section titled “privacy_marketing_set (client)”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.
balance_alert_get (client)
Section titled “balance_alert_get (client)”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.
balance_alert_save (client)
Section titled “balance_alert_save (client)”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.
support_pin (client)
Section titled “support_pin (client)”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.
support_pin_new (client)
Section titled “support_pin_new (client)”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.
affiliate_get (client)
Section titled “affiliate_get (client)”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.
affiliate_join (client)
Section titled “affiliate_join (client)”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.
affiliate_referrals (client)
Section titled “affiliate_referrals (client)”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.
affiliate_entries (client)
Section titled “affiliate_entries (client)”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.
affiliate_payout_request (client)
Section titled “affiliate_payout_request (client)”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.
id_document_status (client)
Section titled “id_document_status (client)”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.
id_document_send (client)
Section titled “id_document_send (client)”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.
privacy_request_deletion (client)
Section titled “privacy_request_deletion (client)”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.
Guest calls
Section titled “Guest calls”create (guest)
Section titled “create (guest)”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.
login (guest)
Section titled “login (guest)”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"}reset_password (guest)
Section titled “reset_password (guest)”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.
update_password (guest)
Section titled “update_password (guest)”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.
required (guest)
Section titled “required (guest)”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"].
custom_fields (guest)
Section titled “custom_fields (guest)”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.
is_email_validation_required (guest)
Section titled “is_email_validation_required (guest)”POST /api/guest/client/is_email_validation_required
Tells whether new clients must confirm their email.
No parameters.
Returns: true or false.
user_password_reset (guest)
Section titled “user_password_reset (guest)”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.
user_invite_accept (guest)
Section titled “user_invite_accept (guest)”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.
twofactor_verify (guest)
Section titled “twofactor_verify (guest)”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.
signin_pin (guest)
Section titled “signin_pin (guest)”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.
passkey_on (guest)
Section titled “passkey_on (guest)”POST /api/guest/client/passkey_on
Tells whether the client sign-in page offers passkey sign-in.
No parameters.
Returns: true or false.
passkey_signin_options (guest)
Section titled “passkey_signin_options (guest)”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.
passkey_signin (guest)
Section titled “passkey_signin (guest)”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.
signin_pin_resend (guest)
Section titled “signin_pin_resend (guest)”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)
google_button (guest)
Section titled “google_button (guest)”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.
google_on (guest)
Section titled “google_on (guest)”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.
affiliate_on (guest)
Section titled “affiliate_on (guest)”POST /api/guest/client/affiliate_on
Tells whether the affiliate program is on.
No parameters.
Returns: true or false.

