Skip to main content
POST
Create a new client

Overview

Create a new client in your workspace. Clients can be associated with projects for billing and invoicing purposes. Each client includes billing configuration, budget settings, and contact information.

Request Body

string
required
The name of the client or company.Example: "Acme Corporation"
string
required
The client’s email address. Must be unique across all clients.Format: Valid email addressExample: "contact@acmecorp.com"
file
Client profile picture or logo.Allowed formats: PNG, JPG, JPEGMax size: As per server configuration
string
Client’s phone number.Example: "+1-555-123-4567"
string
Company name (if different from client name).Example: "Acme Corporation Inc."
string
Client’s website URL.Example: "https://www.acmecorp.com"

Billing Address

string
Primary billing address line.Example: "123 Main Street"
string
Secondary billing address line (suite, apartment, etc.).Example: "Suite 100"
string
City for billing address.Example: "San Francisco"
string
State or province for billing address.Example: "California"
string
ZIP or postal code for billing address.Example: "94102"
string
Country for billing address.Example: "United States"

Invoice Settings

string
Custom invoice notes for this client (if not using org_notes).Example: "Payment due within 30 days of invoice date."
integer
Custom net payment terms in days (if not using org_net_term).Example: 30
string
Client’s tax identification number.Example: "12-3456789"
number
Tax rate percentage for invoices.Example: 8.5

Budget Settings

string
Type of budget tracking.Allowed values: "total_cost", "hours_cost"Example: "total_cost"
number
Budget amount in currency.Example: 50000.00
number
Budget amount in hours (for hours_cost type).Example: 500
integer
Percentage at which to notify about budget usage.Example: 80

Response

object
The created client object.

Example Request

Example Request (JavaScript)

Example Request - With Profile Picture

Example Request (JavaScript with File Upload)

Example Response

Error Responses

Default Invoice Settings

When a client is created, the following default invoice settings are applied:

Default Budget Settings

Organization Settings Inheritance

Using org_notes

  • When true: Client inherits organization’s default invoice notes
  • When false: Custom notes can be specified

Using org_net_term

  • When true: Client inherits organization’s default payment terms
  • When false: Custom net terms can be specified

File Upload

Profile Picture

  • Allowed formats: PNG, JPG, JPEG only
  • Storage: Uploaded to Amazon S3
  • Path: profiles/ directory
  • URL: Full S3 URL returned in response
  • Security: Only image files allowed, other formats rejected

Address Handling

Billing address is automatically copied to mailing address:
  • billing_address1mailing_address1
  • billing_address2mailing_address2
  • citymailing_city
  • statemailing_state
  • zipcodemailing_zip

Webhook Integration

After successful client creation, a Zapier webhook is triggered:

Name Sanitization

Client names are automatically sanitized by removing:
  • Single quotes (')
  • Double quotes (")
  • Commas (,)
  • Semicolons (;)
  • Angle brackets (<, >)
  • Square brackets ([, ])
  • Exclamation marks (!)
  • Plus signs (+)
  • Pipe symbols (|)

Notes

  • Email uniqueness: Client email must be unique across the entire system
  • Team assignment: Client is automatically assigned to your current team
  • User tracking: Your user ID is recorded as the creator
  • Profile storage: Profile pictures are stored on S3 and returned as full URLs
  • Address duplication: Billing address is copied to mailing address
  • Budget tracking: Budget settings can be configured per client
  • Invoice automation: Various invoice settings can be customized
  • Webhook triggers: Zapier webhooks fire on successful creation
  • Character filtering: Client names are sanitized for database safety

Best Practices

  • Always provide complete billing address for invoicing
  • Use organization defaults (org_notes, org_net_term) for consistency
  • Set appropriate budget limits and notification thresholds
  • Upload high-quality logos for professional invoices
  • Verify email uniqueness before submission
  • Configure tax rates according to client location
  • Set realistic payment terms based on client relationship

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

name
string
required
Example:

"Acme Corporation"

email
string<email>
required
Example:

"contact@acmecorp.com"

phone
string
Example:

"+1-555-123-4567"

company
string
Example:

"Acme Corporation Inc."

website
string<uri>
Example:

"https://www.acmecorp.com"

billing_address1
string
Example:

"123 Main Street"

billing_address2
string
Example:

"Suite 100"

city
string
Example:

"San Francisco"

state
string
Example:

"California"

zipcode
string
Example:

"94102"

country
string
Example:

"United States"

notes
string
net_term
integer
Example:

30

tax_id
string
Example:

"12-3456789"

tax_rate
number<float>
Example:

8.5