Create Client - Thareja API Documentation

Create a new client

curl --request POST \
  --url https://app.thareja.ai/api/v1/client/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Corporation",
  "email": "contact@acmecorp.com",
  "phone": "+1-555-123-4567",
  "company": "Acme Corporation Inc.",
  "website": "https://www.acmecorp.com",
  "billing_address1": "123 Main Street",
  "billing_address2": "Suite 100",
  "city": "San Francisco",
  "state": "California",
  "zipcode": "94102",
  "country": "United States",
  "notes": "<string>",
  "net_term": 30,
  "tax_id": "12-3456789",
  "tax_rate": 8.5
}
'

{
  "error": 400,
  "message": "The email has already been taken."
}

POST

api

client

create

Create a new client

curl --request POST \
  --url https://app.thareja.ai/api/v1/client/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Acme Corporation",
  "email": "contact@acmecorp.com",
  "phone": "+1-555-123-4567",
  "company": "Acme Corporation Inc.",
  "website": "https://www.acmecorp.com",
  "billing_address1": "123 Main Street",
  "billing_address2": "Suite 100",
  "city": "San Francisco",
  "state": "California",
  "zipcode": "94102",
  "country": "United States",
  "notes": "<string>",
  "net_term": 30,
  "tax_id": "12-3456789",
  "tax_rate": 8.5
}
'

{
  "error": 400,
  "message": "The email has already been taken."
}

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

name

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"

profile

file

Client profile picture or logo.Allowed formats: PNG, JPG, JPEGMax size: As per server configuration

phone

string

Client’s phone number.Example: "+1-555-123-4567"

company

string

Company name (if different from client name).Example: "Acme Corporation Inc."

website

string

Client’s website URL.Example: "https://www.acmecorp.com"

Billing Address

billing_address1

string

Primary billing address line.Example: "123 Main Street"

billing_address2

string

Secondary billing address line (suite, apartment, etc.).Example: "Suite 100"

city

string

City for billing address.Example: "San Francisco"

state

string

State or province for billing address.Example: "California"

zipcode

string

ZIP or postal code for billing address.Example: "94102"

country

string

Country for billing address.Example: "United States"

Invoice Settings

notes

string

Custom invoice notes for this client (if not using org_notes).Example: "Payment due within 30 days of invoice date."

net_term

integer

Custom net payment terms in days (if not using org_net_term).Example: 30

tax_id

string

Client’s tax identification number.Example: "12-3456789"

tax_rate

number

Tax rate percentage for invoices.Example: 8.5

Budget Settings

budget_type

string

Type of budget tracking.Allowed values: "total_cost", "hours_cost"Example: "total_cost"

budget_cost

number

Budget amount in currency.Example: 50000.00

budget_hours

number

Budget amount in hours (for hours_cost type).Example: 500

budget_notify_at

integer

Percentage at which to notify about budget usage.Example: 80

Response

success

object

The created client object.

Show properties

integer

Unique identifier for the client.

name

string

Client name.

string

Client email address.

profile

string

URL to client profile picture/logo.

phone

string

Client phone number.

company

string

Company name.

website

string

Client website URL.

team_id

integer

Team ID this client belongs to.

user_id

integer

User ID who created the client.

invoices

object

Invoice configuration settings.

budget

object

Budget configuration settings.

created_at

string

Timestamp when client was created.

updated_at

string

Timestamp when client was last updated.

Example Request

curl --request POST \
  --url https://staging.thareja.org/api/v3/client/create \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Corporation",
    "email": "contact@acmecorp.com",
    "phone": "+1-555-123-4567",
    "company": "Acme Corporation Inc.",
    "website": "https://www.acmecorp.com",
    "billing_address1": "123 Main Street",
    "billing_address2": "Suite 100",
    "city": "San Francisco",
    "state": "California",
    "zipcode": "94102",
    "country": "United States",
    "org_notes": true,
    "org_net_term": true,
    "tax_id": "12-3456789",
    "tax_rate": 8.5,
    "budget_type": "total_cost",
    "budget_cost": 50000.00,
    "budget_notify_at": 80
  }'

Example Request (JavaScript)

fetch('https://staging.thareja.org/api/v3/client/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Acme Corporation",
    email: "contact@acmecorp.com",
    phone: "+1-555-123-4567",
    company: "Acme Corporation Inc.",
    website: "https://www.acmecorp.com",
    billing_address1: "123 Main Street",
    billing_address2: "Suite 100",
    city: "San Francisco",
    state: "California",
    zipcode: "94102",
    country: "United States",
    org_notes: true,
    org_net_term: true,
    tax_id: "12-3456789",
    tax_rate: 8.5,
    budget_type: "total_cost",
    budget_cost: 50000.00,
    budget_notify_at: 80
  })
})
.then(response => response.json())
.then(data => console.log(data));

Example Request - With Profile Picture

curl --request POST \
  --url https://staging.thareja.org/api/v3/client/create \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'name="Acme Corporation"' \
  --form 'email="contact@acmecorp.com"' \
  --form 'phone="+1-555-123-4567"' \
  --form 'profile=@/path/to/logo.png' \
  --form 'org_notes=true' \
  --form 'org_net_term=true'

Example Request (JavaScript with File Upload)

const formData = new FormData();
formData.append('name', 'Acme Corporation');
formData.append('email', 'contact@acmecorp.com');
formData.append('phone', '+1-555-123-4567');
formData.append('profile', fileInput.files[0]);
formData.append('org_notes', 'true');
formData.append('org_net_term', 'true');

fetch('https://staging.thareja.org/api/v3/client/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  },
  body: formData
})
.then(response => response.json())
.then(data => console.log(data));

Example Response

{
  "success": {
    "id": 10,
    "name": "Acme Corporation",
    "email": "contact@acmecorp.com",
    "profile": "https://s3.amazonaws.com/bucket/profiles/client-logo.png",
    "phone": "+1-555-123-4567",
    "company": "Acme Corporation Inc.",
    "website": "https://www.acmecorp.com",
    "team_id": 1,
    "user_id": 1,
    "invoices": {
      "tax_id": "12-3456789",
      "late_fee": "no",
      "lineItem": "project-date",
      "net_term": 30,
      "tax_rate": 8.5,
      "frequency": "weekly",
      "delay_days": 5,
      "fixedPrice": 0,
      "autoInvoice": "off",
      "lineItemText": "By user Project and Date",
      "amountBasedOn": "hourly",
      "reminder_days": "10",
      "include_expense": "no",
      "include_non_billable_time": "no"
    },
    "budget": {
      "budgetType": "total_cost",
      "rate": "bill",
      "cost": 50000.00,
      "hours": 0,
      "notifyAt": 80,
      "reset": "never",
      "startDate": null,
      "include_non_billable_time": true
    },
    "isInternalClient": false,
    "created_at": "2025-11-28T10:30:00Z",
    "updated_at": "2025-11-28T10:30:00Z"
  }
}

Error Responses

{
  "error": 400,
  "message": "The email has already been taken."
}

Default Invoice Settings

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

Setting	Default Value	Description
`late_fee`	`no`	Late fee charges disabled
`lineItem`	`project-date`	Invoice line items by project and date
`net_term`	`30`	30-day payment terms (or org default)
`tax_rate`	`0`	No tax rate (unless specified)
`frequency`	`weekly`	Weekly invoice generation
`delay_days`	`5`	5-day delay before auto-invoice
`autoInvoice`	`off`	Auto-invoicing disabled
`amountBasedOn`	`hourly`	Hourly-based billing
`reminder_days`	`10`	Payment reminder 10 days after
`include_expense`	`no`	Expenses not included
`include_non_billable_time`	`no`	Non-billable time excluded

Default Budget Settings

Setting	Default Value	Description
`budgetType`	`total_cost`	Track by total cost
`rate`	`bill`	Use billable rate
`cost`	`0`	No budget limit
`hours`	`0`	No hour limit
`notifyAt`	`80`	Notify at 80% usage
`reset`	`never`	Budget never resets
`include_non_billable_time`	`true`	Include non-billable

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_address1
billing_address2 → mailing_address2
city → mailing_city
state → mailing_state
zipcode → mailing_zip

Webhook Integration

After successful client creation, a Zapier webhook is triggered:

{
  "event": "new_client",
  "payload": {
    "id": 10,
    "name": "Acme Corporation",
    "profile": "https://s3.url/logo.png",
    "retrieved_at": "2025-11-28 10:30:00"
  },
  "criteria": {
    "team_id": 1
  }
}

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

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

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"

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

Send Team Invitation Create Task

​Overview

​Request Body

​Billing Address

​Invoice Settings

​Budget Settings

​Response

​Example Request

​Example Request (JavaScript)

​Example Request - With Profile Picture

​Example Request (JavaScript with File Upload)

​Example Response

​Error Responses

​Default Invoice Settings

​Default Budget Settings

​Organization Settings Inheritance

​Using org_notes

​Using org_net_term

​File Upload

​Profile Picture

​Address Handling

​Webhook Integration

​Name Sanitization

​Notes

​Best Practices

​Related Endpoints

Authorizations

Body

Overview

Request Body

Billing Address

Invoice Settings

Budget Settings

Response

Example Request

Example Request (JavaScript)

Example Request - With Profile Picture

Example Request (JavaScript with File Upload)

Example Response

Error Responses

Default Invoice Settings

Default Budget Settings

Organization Settings Inheritance

Using `org_notes`

Using `org_net_term`

File Upload

Profile Picture

Address Handling

Webhook Integration

Name Sanitization

Notes

Best Practices

Related Endpoints