× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

Projects

General Info

Projects in FreshBooks are used to track business projects and related information such as hourly rate, service(s) being offered, projected end date…etc

Access Requirements

AccessRequires Authorization
Scopesuser:projects:read
user:projects:write

Important Note

When using GET calls for Projects and Time Tracking, please leave out the Content Type from your header.

Includes

There are no includes for projects.

Filters

Filter TypeNameDescription
Boolactivetrue marks that the project is still an active project
Boolcompletetrue marks that the project has been completed
Boolinclude_logged_durationtrue returns the time logged for a project (in seconds)
Datetimeupdated_sincematches projects that have been updated at or after the specified utc date/time
Boolskip_grouptrue returns projects without the group field

Sort Fields

Sort FieldDescription
created_atSort by the creation date of the projects
due_dateSort by the due date of the projects
titleSort by the project titles alphabetically

Field Descriptions

underlined fields are required on creation

FieldTypeDescription
due_dateDatedate of projected completion.
fixed_pricestringused for flat-rate projects. Represents the amount being charged to the client for the project
groupobjectsubfields: pending_invitations, id, members
pending_invitationsstring arraythe pending invites to employees and contractors within the project
idintUnique id of group membership
membersobjectsubfields: first_name, last_name, role, identity_id, active, company, id, email
first_namestringfirst name of the identity
last_namestringlast name of the identity
rolestringnamed role identity holds in group
identity_idintThe unique id for the identity
activeboolwhether the project is active or not
companystringthe name of the business
idintunique id for the membership
emailstringemail of identity
descriptionstringdescription of project
completeboolwhether the project is completed or not
titlestringthe project’s title
project_typestringtype of project: fixed_price, hourly_rate
budgetintbudget for project
updated_atDateTimethe time the project was last updated
servicesobjectsubfields: business_id, name, id
business_idintunique id for business
namestringthe name of the service
idintservice id
ratestringthe hourly rate of the project. Only applies to hourly_rate projects
client_idintunique id of the client being billed for the project
created_atDateTimethe date/time the project was created
logged_durationintthe time logged for the project in seconds
idintunique id for the project
billing_methodstringthe method of payment for the project
internalboolclarifies that the project is internally within the company (client is the company)

Get a Single Project

Request: GET "https://api.freshbooks.com/projects/business/<business_id>/project/<project_id>"

Response:


{
  "project":  {
    "due_date": "2017-07-31",
    "links": {
      "self": "/service/comments/projects/779597",
      "threads": "/service/comments/projects/779597/threads"
    },
    "fixed_price": "34.00",
    "group": {
      "pending_invitations": [],
      "id": 1177789,
      "members": [
        {
          "first_name": "Brian",
          "last_name": "Wyatt",
          "role": "owner",
          "identity_id": 418859,
          "active": true,
          "company": "Brain Wyatt & Co",
          "id": 1971689,
          "email": "test@example.com"
        }
      ]
    },
    "description": null,
    "complete": false,
    "title": "My Cool Project",
    "project_type": "fixed_price",
    "budget": 1440000,
    "updated_at": "2017-07-12T15:00:53",
    "sample": false,
    "services": [
      {
        "business_id": 373845,
        "name": "Software as Service",
        "id": 300088
      },
      {
        "business_id": 373845,
        "name": "Baking Pies",
        "id": 873675
      }
    ],
    "rate": null,
    "internal": false,
    "client_id": 97487,
    "active": true,
    "created_at": "2017-07-12T15:00:53",
    "logged_duration": null,
    "id": 779597,
    "billing_method": "project_rate"
  }
}

Create a Single Project

Request: POST "https://api.freshbooks.com/projects/business/<business_id>/project"


{
  "project": {
    "title": "My Cool Project",
    "client_id": "97499",
    "project_type": "fixed_price",
    "fixed_price": "500"
  }
}


Response:


{
  "project": {
    "due_date": null,
    "links": {
      "self": "/service/comments/projects/779803",
      "threads": "/service/comments/projects/779803/threads"
    },
    "fixed_price": "500",
    "group": {
      "pending_invitations": null,
      "id": 1178154,
      "members": [
        {
          "first_name": "Brian",
          "last_name": "Wyatt",
          "role": "owner",
          "identity_id": 418859,
          "active": true,
          "company": "Brian Wyatt & Co",
          "id": 1972067,
          "email": "test@example.com"
        }
      ]
    },
    "description": null,
    "complete": false,
    "title": "My Cool Project",
    "project_type": "fixed_price",
    "budget": null,
    "updated_at": "2017-07-12T17:22:25",
    "sample": false,
    "services": [],
    "rate": null,
    "internal": false,
    "client_id": 97499,
    "active": true,
    "created_at": "2017-07-12T17:22:25",
    "logged_duration": null,
    "id": 779803,
    "billing_method": null
  }
}

Update a Project

Request: PUT "https://api.freshbooks.com/projects/business/<business_id>/project/<project_id>"


{
  "project": {
    "title": "New Title",
    "due_date": "2017-07-12",
    "client_id": 97487
  }
}


Response:


{
  "project":  {
    "due_date": "2017-07-12",
    "links": {
      "self": "/service/comments/projects/779597",
      "threads": "/service/comments/projects/779597/threads"
    },
    "fixed_price": "34.00",
    "group": {
      "pending_invitations": [],
      "id": 1177789,
      "members": [
        {
          "first_name": "Brian",
          "last_name": "Wyatt",
          "role": "owner",
          "identity_id": 418859,
          "active": true,
          "company": "Brain Wyatt & Co",
          "id": 1971689,
          "email": "test@example.com"
        }
      ]
    },
    "description": null,
    "complete": false,
    "title": "New Title",
    "project_type": "fixed_price",
    "budget": 1440000,
    "updated_at": "2017-07-12T15:00:53",
    "sample": false,
    "services": [
      {
        "business_id": 373845,
        "name": "Software as Service",
        "id": 300088
      },
      {
        "business_id": 373845,
        "name": "Baking Pies",
        "id": 873675
      }
    ],
    "rate": null,
    "internal": false,
    "client_id": 97487,
    "active": true,
    "created_at": "2017-07-12T15:00:53",
    "logged_duration": null,
    "id": 779597,
    "billing_method": "project_rate"
  }
}

Delete a Single Project

Request: DELETE https://api.freshbooks.com/projects/business/<business_id>/project/<project_id>


{}


Response:


{
  "response": { }
}

List Projects

Request: GET “https://api.freshbooks.com/projects/business/<business_id>/projects

Response:


{
  "meta": {
    "per_page": 15,
    "total": 7,
    "page": 0,
    "pages": 1
  }
  "projects": [
    {
      // same format as single project
    },
    {
      // same format as single project
    },
    {
      // same format as single project
    }
  ],
}