Help

Lookup lists

Read these lists to find the ids that other endpoints need. The ids are stable, so you can look them up once and cache them. Every list is paginated (see Pagination).

List Used for Needs
Project statuses project_status_id on opportunities and converts api_read
Lead scores lead_score_id on opportunities api_read
Cost types cost_type_id on costs api_read, read_costs
Finance accounts finance_account_id on cost line items api_read, read_costs
Members member_id on costs and time api_read, read_account_users or manage_permissions
Companies company_id and client_company_id See Companies and contacts

Project statuses

GET /api/v1/project_statuses lists the statuses of the account’s opportunity template, then of its project template, each in list order.

Parameter Meaning
type opportunity or project. Any other value returns 422 invalid_input 
[
  {
    "id": 401,
    "name": "Not Started",
    "type": "project",
    "position": 1,
    "default": true,
    "complete_status": false,
    "sales_status_type": "standard",
    "default_successful_status": false,
    "default_lost_status": false,
    "colour": "#94a3b8"
  }
]
Field Meaning
type opportunity (for opportunities) or project (for converts)
default New records take this status when none is given
complete_status The status marks the record complete
sales_status_type standard, won or lost
default_successful_status, default_lost_status The template’s chosen won and lost statuses

Lead scores

GET /api/v1/lead_scores lists the lead scores of the opportunity template, in list order.

[
  {"id": 51, "name": "Warm", "percentage": 50, "default": true, "position": 1}
]

Cost types

GET /api/v1/cost_types lists the account’s cost types, in name order. Deleted cost types are left out. No filters.

[
  {
    "id": 610,
    "name": "Subcontractor",
    "code": "SUB",
    "description": "Trade packages let to subcontractors",
    "default": false,
    "expense_default": false,
    "default_finance_account_id": 310,
    "line_item_code_id": null
  }
]
Field Meaning
default The account’s default cost type. A new cost still needs a cost_type_id
expense_default The default cost type for expense claims
default_finance_account_id Given to a cost line item sent without a finance account, or null
line_item_code_id A line item code the cost type applies to its lines, or null

Finance accounts

GET /api/v1/finance_accounts lists the account’s chart of accounts, in code then name order.

Parameter Meaning
account_type Only accounts of this type. An unknown type returns 422 invalid_input, and the message lists the types
include_hidden true also returns retired accounts 
[
  {"id": 310, "name": "Subcontractors", "code": "310", "account_type": "expense", "default": false, "visible": true, "tax_rate_id": 12}
]

visible is false for a retired account. A cost line item cannot use a retired account. tax_rate_id is copied onto a cost line item that uses the account.

Members

GET /api/v1/members lists the account’s members of staff, in name order. Removed members are left out unless you ask for them. It needs read_account_users or manage_permissions.

Parameter Meaning
search Matches the member’s name
include_deleted true also returns removed members 
[
  {
    "id": 4821,
    "name": "Jordan Reed",
    "full_name": "Jordan Reed",
    "email": "jordan@example.com",
    "role": "member",
    "active": true,
    "default_resource_type_id": 88
  }
]
Field Meaning
id The member_id used by costs and tracked times
name The member’s name in this account. A staff cost shows it as supplier_name
full_name The person’s own name. Tracked times show it as member_name
email The person’s sign-in email
role admin, member or timesheet_only
active false for a removed member. A new cost refuses a removed member
default_resource_type_id The member’s default resource type, or null