Create a client workspace
/firm-partners/firm/clientsCreates a client workspace with its own books, owned and paid for by the firm.
The client gets full bookkeeping, the default chart of accounts for its country, and the firm’s staff as members, so the same key reaches it at once with `count-workspace-id` set to the returned `workspace.id`. The firm owns the client and is billed for it; the client does not sign in or approve anything. Needs the `firm:write` scope (the bare `write` grant also covers it) and a key with access to all client workspaces. Send `externalReference` to make retries safe: a firm client with that reference is returned with 200 and `created: false`, and the rest of the body is ignored. Creating a client takes several seconds.
Request body
namestringrequiredWorkspace (business) name. Up to 255 characters.
countrystringrequiredTwo-letter ISO country code, such as `US`. Decides the default chart of accounts and, when `currency` is not sent, the currency. Cannot be changed later.
currencystringThree-letter ISO currency code. Defaults from `country`.
externalReferencestringYour own id for this client, up to 255 characters, unique within the firm. Makes retries safe; returned on List client workspaces.
clientKindstringWhether the client is an individual or a business.
One of: individual, business
emailstringWorkspace email. Addresses on disposable email domains are refused with 400.
websitestringWorkspace website.
typestringBusiness type, as chosen in the app.
subTypestringBusiness sub-type, as chosen in the app.
statestringState or region of the business.
businessAddressobjectThe business address. Every field is optional.
streetstringStreet line 1.
street2stringStreet line 2.
citystringCity.
statestringState or region.
zipCodestringPostal code.
countrystringCountry.
contactDetailsobjectThe client’s main contact. Every field is optional.
firstNamestringFirst name.
lastNamestringLast name.
emailstringEmail address.
phonestringPhone number.
configurationobjectWorkspace preferences.
timezonestringIANA timezone, such as `America/Chicago`.
brandPrimaryColorstringBrand colour as a hex value without `#`.
biostringShort description of the business.
Responses
200The firm already has a client with this `externalReference`. Nothing new was created.201The client workspace was created.400The body is invalid (for example `country: Required`), or `email` is on a disposable email domain.401Missing signing headers, an invalid HMAC signature, or a timestamp more than 5 minutes off. Troubleshoot403The key’s scope lacks `firm:write`, the key is limited to selected client workspaces, or the key is inactive. Troubleshoot409Another request with the same `externalReference` is still creating this client. Retry after a moment.429The per-minute or daily client creation limit, or the 100 requests per minute rate limit, was reached. Troubleshoot503The client could not be created right now. Retry with the same `externalReference`.https://api.getcount.com/firm-partners/firm/clientsimport crypto from 'node:crypto';
const BASE_URL = 'https://api.getcount.com';
const CLIENT_ID = process.env.COUNT_CLIENT_ID;
const CLIENT_SECRET = process.env.COUNT_CLIENT_SECRET;
const method = 'POST';
const signingPath = '/firm/clients';
const timestamp = Math.floor(Date.now() / 1000).toString();
const body = {
"name": "Maple Grove HOA",
"country": "US",
"clientKind": "business",
"email": "board@maplegrovehoa.example",
"businessAddress": {
"street": "1 Maple Grove Dr",
"city": "Austin",
"state": "TX",
"zipCode": "78701",
"country": "US"
},
"contactDetails": {
"firstName": "Pat",
"lastName": "Rivera",
"email": "pat@maplegrovehoa.example",
"phone": "+1 512 555 0142"
},
"externalReference": "hoa-27"
};
const bodyString = JSON.stringify(body);
const bodyHash = crypto.createHash('sha256').update(bodyString).digest('hex');
const baseString = `${method}:${signingPath}:${timestamp}:${bodyHash}`;
const signature = crypto.createHmac('sha256', CLIENT_SECRET).update(baseString).digest('hex');
const response = await fetch(`${BASE_URL}/firm-partners/firm/clients`, {
method,
headers: {
'x-client-id': CLIENT_ID,
'x-timestamp': timestamp,
'x-signature': signature,
'Content-Type': 'application/json',
},
body: bodyString,
});
console.log(await response.json());{
"status": "success",
"message": "Client workspace already exists for this externalReference.",
"data": {
"workspace": {
"id": "6f5e4d3c-2b1a-4c9d-8e7f-0a1b2c3d4e5f",
"name": "Maple Grove HOA",
"currency": "USD",
"isOwnedByFirm": true,
"externalReference": "hoa-27"
},
"created": false
}
}