Clients

Manage client accounts and associate them with projects

Endpoints

GET/v2/clients/{client_id}
PUT/v2/clients/{client_id}
PUT/v2/clients/{client_id}/update_metadata
GET/v2/organizations/{organization_id}/clients
POST/v2/organizations/{organization_id}/clients

Get client

GET/v2/clients/{client_id}

Returns the client with the given ID.

Parameters

Name	In	Type	Description
client_idrequired	path	integer (int32)	Client ID

Responses

200A client

object

clientobject
object
Client model
- idinteger required
  Client ID
- organization_idinteger required
  Organization ID
- namestring required
  Client Name
- emailsarray required
  Emails to default send invoices to
  array<string>
  Emails to default send invoices to
  items
  string
- phonestring required
  Phone Number
- addressstring required
  Address
- project_idsarray required
  List of projects
  array<integer>
  List of projects
  items
  integer(int64)
- inherit_invoice_notesboolean
  True if the organizations invoice notes will be used
- invoice_notesstring
  Notes (Shown on invoices)
- inherit_net_termsboolean
  True if the organizations net terms will be used
- net_termsstring
  Amount of days the invoice must be paid once created
- statusstring required
  Client status
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- budgetobject
  object
  - typestring required
    The budget type
  - ratestring
    The budget rate type
  - costnumber
    The budget cost limit
  - hoursnumber
    The budget hours limit
  - start_datestring
    The budget start date
  - alertsobject required
    object
    near_limitinteger required
    The budget near limit percentage
    notify_enabledboolean required
    Whether budget notifications are enabled
    notify_all_membersboolean required
    Whether to notify all project members
    notify_groupstring
    The group to notify
  - recurrencestring
    The budget recurrence frequency
  - recurrence_startinteger
    Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
  - include_non_billableboolean required
    Whether the budget includes non-billable time
  - stop_timer_when_budget_reachedboolean required
    Whether to stop timers when budget is reached
  - stop_atinteger
    The budget percentage at which timers stop
- metadataobject required
  Metadata attached to the client
  object
  Metadata attached to the client

Example response

json

{
  "client": {
    "id": 0,
    "organization_id": 0,
    "name": "string",
    "emails": [
      "string"
    ],
    "phone": "string",
    "address": "string",
    "project_ids": [
      0
    ],
    "inherit_invoice_notes": false,
    "invoice_notes": "string",
    "inherit_net_terms": false,
    "net_terms": "string",
    "status": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "budget": {
      "type": "string",
      "rate": "string",
      "cost": 0,
      "hours": 0,
      "start_date": "2024-01-15",
      "alerts": {
        "near_limit": 0,
        "notify_enabled": false,
        "notify_all_members": false,
        "notify_group": "string"
      },
      "recurrence": "string",
      "recurrence_start": 0,
      "include_non_billable": false,
      "stop_timer_when_budget_reached": false,
      "stop_at": 0
    },
    "metadata": {}
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Update client

PUT/v2/clients/{client_id}

Updates a client.

Returns the updated client.

Only pass in the fields you want to change. To unset the budget, specify null as the value. To update the budget, you must specify the complete budget configuration. To clear invoice_notes or net_terms (to use organization defaults), specify null as the value.

Parameters

Name	In	Type	Description
client_idrequired	path	integer (int32)	Client ID

Request body

object

Update client

namestring
The new name of the client
emailsarray
The new emails for the client
array<string>
The new emails for the client
items
string
phonestring
Client phone number
addressstring
Client address
project_idsarray
Client projects
array<integer>
Client projects
items
integer(int32)
invoice_notesstring
Notes (Shown on invoices)
net_termsinteger
Amount of days the invoice must be paid once created
statusstring
Client status.
metadataarray
Client metadata. See the update_metadata endpoint
array<object>
Client metadata. See the update_metadata endpoint
items
object
- keystring required
  The metadata key
- valuestring required
  The value for the metadata key
budgetobject
Budget configuration
object
Budget configuration
- typestring required
  The method for controlling the budget
- ratestring
  When budget type is cost, specifies which rate to use.
- costnumber
  When budget type is cost. defines the cost limit.
- hoursnumber
  When budget type is hours. defines the hours limit.
- start_datestring
  The start date for the budget.
- recurrencestring
  If given, makes budget reset on a weekly or monthly basis
- recurrence_startinteger
  Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
- include_non_billableboolean
  Whether the budget includes non billable time
- stop_timer_when_budget_reachedboolean
  Whether to stop timers when budget limit is reached
- stop_atinteger required
  The budget percentage at which timers stop automatically
- alertsobject
  object
  - near_limitinteger
    The percentage threshold for notifying when approaching the budget.
  - notify_enabledboolean
    Whether budget notifications are enabled
  - notify_all_membersboolean
    Whether to notify all project members
  - notify_groupstring
    The group to notify

Responses

200A client

object

clientobject
object
Client model
- idinteger required
  Client ID
- organization_idinteger required
  Organization ID
- namestring required
  Client Name
- emailsarray required
  Emails to default send invoices to
  array<string>
  Emails to default send invoices to
  items
  string
- phonestring required
  Phone Number
- addressstring required
  Address
- project_idsarray required
  List of projects
  array<integer>
  List of projects
  items
  integer(int64)
- inherit_invoice_notesboolean
  True if the organizations invoice notes will be used
- invoice_notesstring
  Notes (Shown on invoices)
- inherit_net_termsboolean
  True if the organizations net terms will be used
- net_termsstring
  Amount of days the invoice must be paid once created
- statusstring required
  Client status
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- budgetobject
  object
  - typestring required
    The budget type
  - ratestring
    The budget rate type
  - costnumber
    The budget cost limit
  - hoursnumber
    The budget hours limit
  - start_datestring
    The budget start date
  - alertsobject required
    object
    near_limitinteger required
    The budget near limit percentage
    notify_enabledboolean required
    Whether budget notifications are enabled
    notify_all_membersboolean required
    Whether to notify all project members
    notify_groupstring
    The group to notify
  - recurrencestring
    The budget recurrence frequency
  - recurrence_startinteger
    Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
  - include_non_billableboolean required
    Whether the budget includes non-billable time
  - stop_timer_when_budget_reachedboolean required
    Whether to stop timers when budget is reached
  - stop_atinteger
    The budget percentage at which timers stop
- metadataobject required
  Metadata attached to the client
  object
  Metadata attached to the client

Example response

json

{
  "client": {
    "id": 0,
    "organization_id": 0,
    "name": "string",
    "emails": [
      "string"
    ],
    "phone": "string",
    "address": "string",
    "project_ids": [
      0
    ],
    "inherit_invoice_notes": false,
    "invoice_notes": "string",
    "inherit_net_terms": false,
    "net_terms": "string",
    "status": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "budget": {
      "type": "string",
      "rate": "string",
      "cost": 0,
      "hours": 0,
      "start_date": "2024-01-15",
      "alerts": {
        "near_limit": 0,
        "notify_enabled": false,
        "notify_all_members": false,
        "notify_group": "string"
      },
      "recurrence": "string",
      "recurrence_start": 0,
      "include_non_billable": false,
      "stop_timer_when_budget_reached": false,
      "stop_at": 0
    },
    "metadata": {}
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Update client metadata

PUT/v2/clients/{client_id}/update_metadata

Updates metadata on the client.

Returns the updated client.

Only specify the metadata keys you want to change. If the metadata key does not exist, it will be created. To remove a key, specify null as the value.

Key requirements:

2-30 characters
Lowercase letters, numbers, and underscores only

Value requirements:

Valid UTF-8 string
Maximum 200 characters

Parameters

Name	In	Type	Description
client_idrequired	path	integer (int32)	Client ID

Request body

object

Update client metadata

metadataarray required
array<object>
items
object
- keystring required
  The metadata key
- valuestring required
  The value for the metadata key

Responses

200A client

object

clientobject
object
Client model
- idinteger required
  Client ID
- organization_idinteger required
  Organization ID
- namestring required
  Client Name
- emailsarray required
  Emails to default send invoices to
  array<string>
  Emails to default send invoices to
  items
  string
- phonestring required
  Phone Number
- addressstring required
  Address
- project_idsarray required
  List of projects
  array<integer>
  List of projects
  items
  integer(int64)
- inherit_invoice_notesboolean
  True if the organizations invoice notes will be used
- invoice_notesstring
  Notes (Shown on invoices)
- inherit_net_termsboolean
  True if the organizations net terms will be used
- net_termsstring
  Amount of days the invoice must be paid once created
- statusstring required
  Client status
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- budgetobject
  object
  - typestring required
    The budget type
  - ratestring
    The budget rate type
  - costnumber
    The budget cost limit
  - hoursnumber
    The budget hours limit
  - start_datestring
    The budget start date
  - alertsobject required
    object
    near_limitinteger required
    The budget near limit percentage
    notify_enabledboolean required
    Whether budget notifications are enabled
    notify_all_membersboolean required
    Whether to notify all project members
    notify_groupstring
    The group to notify
  - recurrencestring
    The budget recurrence frequency
  - recurrence_startinteger
    Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
  - include_non_billableboolean required
    Whether the budget includes non-billable time
  - stop_timer_when_budget_reachedboolean required
    Whether to stop timers when budget is reached
  - stop_atinteger
    The budget percentage at which timers stop
- metadataobject required
  Metadata attached to the client
  object
  Metadata attached to the client

Example response

json

{
  "client": {
    "id": 0,
    "organization_id": 0,
    "name": "string",
    "emails": [
      "string"
    ],
    "phone": "string",
    "address": "string",
    "project_ids": [
      0
    ],
    "inherit_invoice_notes": false,
    "invoice_notes": "string",
    "inherit_net_terms": false,
    "net_terms": "string",
    "status": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "budget": {
      "type": "string",
      "rate": "string",
      "cost": 0,
      "hours": 0,
      "start_date": "2024-01-15",
      "alerts": {
        "near_limit": 0,
        "notify_enabled": false,
        "notify_all_members": false,
        "notify_group": "string"
      },
      "recurrence": "string",
      "recurrence_start": 0,
      "include_non_billable": false,
      "stop_timer_when_budget_reached": false,
      "stop_at": 0
    },
    "metadata": {}
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

List organization clients

GET/v2/organizations/{organization_id}/clients

Returns a collection of clients for the given organization.

Results can be filtered by status.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)
page_start_id	query	integer (int32)	The page start ID.
page_limit	query	integer (int32)	The default page size
status	query	string	Client status Possible values`activearchivedall`
include	query	array string[]	Specify related data to side load. Possible values`projects`

Responses

200A list of clients

object

clientsarray
array<object>
items
object
Client model
- idinteger required
  Client ID
- organization_idinteger required
  Organization ID
- namestring required
  Client Name
- emailsarray required
  Emails to default send invoices to
  array<string>
  Emails to default send invoices to
  items
  string
- phonestring required
  Phone Number
- addressstring required
  Address
- project_idsarray required
  List of projects
  array<integer>
  List of projects
  items
  integer(int64)
- inherit_invoice_notesboolean
  True if the organizations invoice notes will be used
- invoice_notesstring
  Notes (Shown on invoices)
- inherit_net_termsboolean
  True if the organizations net terms will be used
- net_termsstring
  Amount of days the invoice must be paid once created
- statusstring required
  Client status
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- budgetobject
  object
  typestring required
  The budget type
  ratestring
  The budget rate type
  costnumber
  The budget cost limit
  hoursnumber
  The budget hours limit
  start_datestring
  The budget start date
  alertsobject required
  object
  near_limitinteger required
  The budget near limit percentage
  notify_enabledboolean required
  Whether budget notifications are enabled
  notify_all_membersboolean required
  Whether to notify all project members
  notify_groupstring
  The group to notify
  recurrencestring
  The budget recurrence frequency
  recurrence_startinteger
  Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
  include_non_billableboolean required
  Whether the budget includes non-billable time
  stop_timer_when_budget_reachedboolean required
  Whether to stop timers when budget is reached
  stop_atinteger
  The budget percentage at which timers stop
- metadataobject required
  Metadata attached to the client
  object
  Metadata attached to the client

Example response

json

{
  "clients": [
    {
      "id": 0,
      "organization_id": 0,
      "name": "string",
      "emails": [
        "string"
      ],
      "phone": "string",
      "address": "string",
      "project_ids": [
        0
      ],
      "inherit_invoice_notes": false,
      "invoice_notes": "string",
      "inherit_net_terms": false,
      "net_terms": "string",
      "status": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "budget": {
        "type": "string",
        "rate": "string",
        "cost": 0,
        "hours": 0,
        "start_date": "2024-01-15",
        "alerts": {
          "near_limit": 0,
          "notify_enabled": false,
          "notify_all_members": false,
          "notify_group": "string"
        },
        "recurrence": "string",
        "recurrence_start": 0,
        "include_non_billable": false,
        "stop_timer_when_budget_reached": false,
        "stop_at": 0
      },
      "metadata": {}
    }
  ]
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

Create client

POST/v2/organizations/{organization_id}/clients

Creates a new client.

Returns the created client.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)

Request body

object

Create client

namestring required
Client name
emailsarray
Default emails when sending an invoice
array<string>
Default emails when sending an invoice
items
string
phonestring
Client phone number
addressstring
Client address
project_idsarray
Project IDs associated with this client
array<string>
Project IDs associated with this client
items
string
invoice_notesstring
Notes (Shown on invoices)
net_termsinteger
Amount of days the invoice must be paid once created
metadataarray
Client metadata. See the update_metadata endpoint
array<object>
Client metadata. See the update_metadata endpoint
items
object
- keystring required
  The metadata key
- valuestring required
  The value for the metadata key
budgetobject
Budget configuration
object
Budget configuration
- typestring required
  The method for controlling the budget
- ratestring
  When budget type is cost, specifies which rate to use.
- costnumber
  When budget type is cost. defines the cost limit.
- hoursnumber
  When budget type is hours. defines the hours limit.
- start_datestring
  The start date for the budget.
- recurrencestring
  If given, makes budget reset on a weekly or monthly basis
- recurrence_startinteger
  Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
- include_non_billableboolean
  Whether the budget includes non billable time
- stop_timer_when_budget_reachedboolean
  Whether to stop timers when budget limit is reached
- stop_atinteger required
  The budget percentage at which timers stop automatically
- alertsobject
  object
  - near_limitinteger
    The percentage threshold for notifying when approaching the budget.
  - notify_enabledboolean
    Whether budget notifications are enabled
  - notify_all_membersboolean
    Whether to notify all project members
  - notify_groupstring
    The group to notify

Responses

200A client

object

clientobject
object
Client model
- idinteger required
  Client ID
- organization_idinteger required
  Organization ID
- namestring required
  Client Name
- emailsarray required
  Emails to default send invoices to
  array<string>
  Emails to default send invoices to
  items
  string
- phonestring required
  Phone Number
- addressstring required
  Address
- project_idsarray required
  List of projects
  array<integer>
  List of projects
  items
  integer(int64)
- inherit_invoice_notesboolean
  True if the organizations invoice notes will be used
- invoice_notesstring
  Notes (Shown on invoices)
- inherit_net_termsboolean
  True if the organizations net terms will be used
- net_termsstring
  Amount of days the invoice must be paid once created
- statusstring required
  Client status
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- budgetobject
  object
  - typestring required
    The budget type
  - ratestring
    The budget rate type
  - costnumber
    The budget cost limit
  - hoursnumber
    The budget hours limit
  - start_datestring
    The budget start date
  - alertsobject required
    object
    near_limitinteger required
    The budget near limit percentage
    notify_enabledboolean required
    Whether budget notifications are enabled
    notify_all_membersboolean required
    Whether to notify all project members
    notify_groupstring
    The group to notify
  - recurrencestring
    The budget recurrence frequency
  - recurrence_startinteger
    Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
  - include_non_billableboolean required
    Whether the budget includes non-billable time
  - stop_timer_when_budget_reachedboolean required
    Whether to stop timers when budget is reached
  - stop_atinteger
    The budget percentage at which timers stop
- metadataobject required
  Metadata attached to the client
  object
  Metadata attached to the client

Example response

json

{
  "client": {
    "id": 0,
    "organization_id": 0,
    "name": "string",
    "emails": [
      "string"
    ],
    "phone": "string",
    "address": "string",
    "project_ids": [
      0
    ],
    "inherit_invoice_notes": false,
    "invoice_notes": "string",
    "inherit_net_terms": false,
    "net_terms": "string",
    "status": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "budget": {
      "type": "string",
      "rate": "string",
      "cost": 0,
      "hours": 0,
      "start_date": "2024-01-15",
      "alerts": {
        "near_limit": 0,
        "notify_enabled": false,
        "notify_all_members": false,
        "notify_group": "string"
      },
      "recurrence": "string",
      "recurrence_start": 0,
      "include_non_billable": false,
      "stop_timer_when_budget_reached": false,
      "stop_at": 0
    },
    "metadata": {}
  }
}

400Invalid parameters

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

401Unauthorized

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

403API access is only for organizations on an active plan

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

404Could not find record

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}

429Rate limit exceeded

object

Hubstaff_Public_V2_Entities_Error model

codestring required
Legacy string error code for backward compatibility
error_codeinteger
Numeric error code for i18n/programmatic handling. Ranges: 10000-10999 (Auth), 11000-11999 (Validation), 12000-12999 (Resource), 13000-13999 (Rate Limit), 14000-14999 (Time Entry/Activity), 15000-15999 (System). See GET /v2/error_codes for full reference.
errorstring required
Human-readable error message
detailsarray
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
array<string>
Per-attribute validation errors: [{attribute, error}]. Present on validation failures.
items
string

Example response

json

{
  "code": "string",
  "error_code": 0,
  "error": "string",
  "details": [
    "string"
  ]
}