Projects

Create and manage projects for time tracking

Endpoints

GET/v2/organizations/{organization_id}/projects
POST/v2/organizations/{organization_id}/projects
GET/v2/projects/{project_id}
PUT/v2/projects/{project_id}
PUT/v2/projects/{project_id}/update_metadata

List organization projects

GET/v2/organizations/{organization_id}/projects

Returns a collection of projects for the given organization.

Results can be filtered by status (active/archived/all) and project_ids[].

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	Project status Possible values`activearchivedall`
include	query	array string[]	Specify related data to side load. Possible values`clients`
project_ids	query	array integer[]	List of project IDs

Responses

200A list of projects

object

projectsarray
array<object>
items
object
Project model
- idinteger required
  Project ID
- namestring required
  Project name
- descriptionstring
  Project description
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- statusstring required
  Project status
- typestring required
  Project type (project, work_order, work_break)
- client_idinteger
  Client ID
- billableboolean required
  Default state of billable attribute for new activity
- 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 project
  object
  Metadata attached to the project
- pay_ratenumber
  Default pay rate for the project
- bill_ratenumber
  Default bill rate for the project

Example response

json

{
  "projects": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "status": "string",
      "type": "string",
      "client_id": 0,
      "billable": false,
      "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": {},
      "pay_rate": 0,
      "bill_rate": 0
    }
  ]
}

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 project

POST/v2/organizations/{organization_id}/projects

Creates a new project.

Returns the created project.

Only name is required. Members can optionally be added with roles: viewer, user, or manager.

Parameters

Name	In	Type	Description
organization_idrequired	path	integer (int32)

Request body

object

Create project

namestring required
Project name
descriptionstring
Project description
metadataarray
Project metadata. See the update_metadata endpoint
array<object>
Project metadata. See the update_metadata endpoint
items
object
- keystring required
  The metadata key
- valuestring required
  The value for the metadata key
membersarray
array<object>
items
object
- user_idinteger required
  User ID
- rolestring required
  Role for the user
- pay_ratenumber
  Default pay rate (will be rounded to 2 decimal places). Set to null to remove the rate
- bill_ratenumber
  Default bill rate (will be rounded to 2 decimal places). Set to null to remove the rate
client_idinteger
The client ID
billableboolean
Whether activity logged against this project is billable by default (default is true)
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
pay_ratenumber
Default pay rate (will be rounded to 2 decimal places). Set to null to remove the rate
bill_ratenumber
Default bill rate (will be rounded to 2 decimal places). Set to null to remove the rate

Responses

201A project

object

projectobject
object
Project model
- idinteger required
  Project ID
- namestring required
  Project name
- descriptionstring
  Project description
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- statusstring required
  Project status
- typestring required
  Project type (project, work_order, work_break)
- client_idinteger
  Client ID
- billableboolean required
  Default state of billable attribute for new activity
- 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 project
  object
  Metadata attached to the project
- pay_ratenumber
  Default pay rate for the project
- bill_ratenumber
  Default bill rate for the project

Example response

json

{
  "project": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "status": "string",
    "type": "string",
    "client_id": 0,
    "billable": false,
    "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": {},
    "pay_rate": 0,
    "bill_rate": 0
  }
}

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"
  ]
}

Get project

GET/v2/projects/{project_id}

Returns the project with the given ID.

Parameters

Name	In	Type	Description
project_idrequired	path	integer (int32)	Project ID

Responses

200A project

object

projectobject
object
Project model
- idinteger required
  Project ID
- namestring required
  Project name
- descriptionstring
  Project description
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- statusstring required
  Project status
- typestring required
  Project type (project, work_order, work_break)
- client_idinteger
  Client ID
- billableboolean required
  Default state of billable attribute for new activity
- 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 project
  object
  Metadata attached to the project
- pay_ratenumber
  Default pay rate for the project
- bill_ratenumber
  Default bill rate for the project

Example response

json

{
  "project": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "status": "string",
    "type": "string",
    "client_id": 0,
    "billable": false,
    "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": {},
    "pay_rate": 0,
    "bill_rate": 0
  }
}

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 project

PUT/v2/projects/{project_id}

Updates a project.

Returns the updated project.

Only pass in the fields you want to change. To unset the budget, specify null. To update the budget, you must specify the complete budget configuration.

When restoring an archived project, you can only change the status column.

Rate handling for pay_rate and bill_rate:

To remove a rate, pass null (e.g., pay_rate: null)
Custom user rates take precedence over default project rates
To apply default project rate to a user, remove their custom rate first

Parameters

Name	In	Type	Description
project_idrequired	path	integer (int32)	Project ID

Request body

object

Update project

namestring
The new name of the project
descriptionstring
The new description of the project
client_idinteger
The client ID
billableboolean
Whether time logged against this project is by default billable
statusstring
The project status.
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
pay_ratenumber
Default pay rate (will be rounded to 2 decimal places). Set to null to remove the rate
bill_ratenumber
Default bill rate (will be rounded to 2 decimal places). Set to null to remove the rate

Responses

200A project

object

projectobject
object
Project model
- idinteger required
  Project ID
- namestring required
  Project name
- descriptionstring
  Project description
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- statusstring required
  Project status
- typestring required
  Project type (project, work_order, work_break)
- client_idinteger
  Client ID
- billableboolean required
  Default state of billable attribute for new activity
- 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 project
  object
  Metadata attached to the project
- pay_ratenumber
  Default pay rate for the project
- bill_ratenumber
  Default bill rate for the project

Example response

json

{
  "project": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "status": "string",
    "type": "string",
    "client_id": 0,
    "billable": false,
    "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": {},
    "pay_rate": 0,
    "bill_rate": 0
  }
}

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 project metadata

PUT/v2/projects/{project_id}/update_metadata

Updates metadata on the project.

Returns the updated project.

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
project_idrequired	path	integer (int32)	Project ID

Request body

object

Update project metadata

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

Responses

200A project

object

projectobject
object
Project model
- idinteger required
  Project ID
- namestring required
  Project name
- descriptionstring
  Project description
- created_atstring required
  When the record was created
- updated_atstring required
  When the record was last updated
- statusstring required
  Project status
- typestring required
  Project type (project, work_order, work_break)
- client_idinteger
  Client ID
- billableboolean required
  Default state of billable attribute for new activity
- 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 project
  object
  Metadata attached to the project
- pay_ratenumber
  Default pay rate for the project
- bill_ratenumber
  Default bill rate for the project

Example response

json

{
  "project": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "status": "string",
    "type": "string",
    "client_id": 0,
    "billable": false,
    "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": {},
    "pay_rate": 0,
    "bill_rate": 0
  }
}

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"
  ]
}