Create a new client
Client
Create Client
Create a new client with billing configuration, budget settings, and contact information
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:
30string
Client’s tax identification number.Example:
"12-3456789"number
Tax rate percentage for invoices.Example:
8.5Budget Settings
string
Type of budget tracking.Allowed values:
"total_cost", "hours_cost"Example: "total_cost"number
Budget amount in currency.Example:
50000.00number
Budget amount in hours (for hours_cost type).Example:
500integer
Percentage at which to notify about budget usage.Example:
80Response
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_address1→mailing_address1billing_address2→mailing_address2city→mailing_citystate→mailing_statezipcode→mailing_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
Related Endpoints
- Get Clients - List all clients
- Get Client - Retrieve client details
- Update Client - Update client information
- Delete Client - Remove a client
- Get Client Invoices - View client invoices
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Example:
"Acme Corporation"
Example:
"contact@acmecorp.com"
Example:
"+1-555-123-4567"
Example:
"Acme Corporation Inc."
Example:
"https://www.acmecorp.com"
Example:
"123 Main Street"
Example:
"Suite 100"
Example:
"San Francisco"
Example:
"California"
Example:
"94102"
Example:
"United States"
Example:
30
Example:
"12-3456789"
Example:
8.5