---
title: "Add a customer · Customers · Practice Manager API · COUNT Partner API"
description: "Creates a new customer in the workspace. POST /firm-partners/workspace/customers"
canonical: "https://developers.getcount.com/practice-manager/reference/customers/add-customer"
source: "https://developers.getcount.com/practice-manager/reference/customers/add-customer"
---
[Customers](https://developers.getcount.com/practice-manager/reference/customers) / Add a customer

# Add a customer

POST `/firm-partners/workspace/customers`

Creates a new customer in the workspace.

Only customer (the name) is required. Addresses, contacts, and taxes can be created inline.

Some fields work differently in US and NZ workspaces

Showing US sales tax and NZ GST rules.

HMAC signature only

[Invoices API](https://developers.getcount.com/practice-manager/reference/invoices) [Projects API](https://developers.getcount.com/practice-manager/reference/projects) [Recurring Invoice Templates API](https://developers.getcount.com/practice-manager/reference/recurring-invoice-templates)

#### Headers

`count-workspace-id` uuid required

UUID of the client workspace to act on. It must be one of your firm's client workspaces (or the firm's own workspace) and within the API key's client workspaces.

#### Request body

`customer` string required

Customer or business name. The only required field.

`email` string

Primary contact email. Optional; does not need to be unique.

`mainPhone` string

Primary phone number. International format recommended.

`website` string

Website URL. Stored with an https:// prefix if the protocol is omitted.

`notes` string

Free-text notes. HTML is sanitized.

`status` enum

Customer status. Defaults to active.

One of: `active`, `inactive`

`paymentTerm` string

Default payment term for invoices (for example net30).

`taxNumber` string

Tax registration number.

`salesRepId` integer

Id of the workspace person to assign as sales representative.

`taxAutoCalculate` boolean

Derive tax from the address. Defaults to false; when true, any `taxes` sent are discarded.

- US· Sales tax Sales tax comes from the shipping (else billing) address.

`taxExcluded` boolean

Mark the customer tax-exempt. Defaults to false.

- US· Sales tax Their taxed invoice lines are raised Non-Taxable unless a line sends `customerExemptionOverridden: true`.
- NZ· GST Their invoice lines are raised with no GST code.

`taxes` array

Tax UUIDs from List tax codes, applied when `taxAutoCalculate` is false. Numeric ids are rejected.

`billingAddress` object

Billing address for the customer.

`street` string

Street address.

`city` string

City or locality.

`state` string

State, province, or region.

`zipCode` string

Postal or ZIP code.

`country` string

Country name or ISO code.

`shippingAddress` object

Shipping address. Same shape as billingAddress.

`contacts` array

Contact people for this customer. The first contact sets the derived contactName.

`firstName` string required

Contact's first name.

`lastName` string required

Contact's last name.

`email` string

Contact's email address.

`phone` string

Contact's phone number.

`isPrimary` boolean

Marks the primary contact.

#### Responses

`201` Customer created successfully.

`400` Bad request — validation failed.

`401` Missing signing headers, an invalid HMAC signature, or a timestamp more than 5 minutes off. [Troubleshoot](https://developers.getcount.com/practice-manager/authentication#errors)

`403` The key is inactive or its scope does not allow this request, the workspace is not managed by your firm or is outside the key's client workspaces, the workspace has no active subscription, or it is portal-only and the route needs bookkeeping. [Troubleshoot](https://developers.getcount.com/practice-manager/authentication#errors)

`404` No workspace exists with the `count-workspace-id` UUID.

`429` Rate limit exceeded (100 requests per minute per firm user of each app, or 10,000 per minute per app). [Troubleshoot](https://developers.getcount.com/practice-manager/authentication#errors)

[Previous GET Get a customer](https://developers.getcount.com/practice-manager/reference/customers/get-customer) [Next PUT Update a customer](https://developers.getcount.com/practice-manager/reference/customers/update-customer)

POST `https://api.getcount.com/firm-partners/workspace/customers`

Request

```javascript
import 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 = '/workspace/customers';
const timestamp = Math.floor(Date.now() / 1000).toString();
const body = {
  "customer": "Acme Corporation",
  "email": "contact@acme.com",
  "mainPhone": "+1234567890",
  "website": "https://acme.com",
  "status": "active",
  "paymentTerm": "net30",
  "billingAddress": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "country": "USA"
  },
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@acme.com",
      "isPrimary": true
    }
  ]
};
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/workspace/customers`, {
  method,
  headers: {
    'x-client-id': CLIENT_ID,
    'x-timestamp': timestamp,
    'x-signature': signature,
    'Content-Type': 'application/json',
    'count-workspace-id': '5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716',
  },
  body: bodyString,
});

console.log(await response.json());
```

Response · 201

```json
{
  "status": "success",
  "message": "success on creating customer",
  "data": {
    "customer": {
      "id": "dfa3219e-6af8-4c53-997a-037534f63a35",
      "customer": "Acme Corporation",
      "email": "contact@acme.com",
      "mainPhone": "+1234567890",
      "website": "https://acme.com",
      "status": "active",
      "notes": "Preferred customer. Net-30 terms.",
      "paymentTerm": "net30",
      "taxNumber": null,
      "taxAutoCalculate": false,
      "taxExcluded": false,
      "contactName": "John Doe",
      "billingAddress": {
        "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12",
        "street": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "zipCode": "94102",
        "country": "USA"
      },
      "shippingAddress": null,
      "contacts": [
        {
          "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john@acme.com",
          "phone": "+1234567890",
          "isPrimary": true
        }
      ],
      "taxes": [],
      "salesRep": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-28T14:22:30.000Z"
    }
  }
}
```
