Project

Freckle is now Noko! Learn how to migrate your apps here

List projects

List all projects the authenticated user has access to

GET /projects/

Parameters

name
Optional string
Only projects containing this text in their name are returned.
Example: name=Gear
project_group_ids
Optional string: a comma-separated list of Project Group IDs to filter by.
Example: project_group_ids=1,2,3
billing_increment
Optional integer
Only projects with this specific billing increment are returned
Example: billing_increment=15
Accepted values: 1, 5, 6, 10, 15 (Default), 20, 30, 60
enabled
Optional boolean
true: return all enabled projects
false returns all archived projects
billable
Optional boolean
true: return all billable projects
false return all unbillable projects.

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/projects?page=2>; rel="next",
 <https://api.nokotime.com/v2/projects?page=5>; rel="last"
[
  {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396",
    "group": {
      "id": 3768,
      "name": "Sprockets, Inc.",
      "url": "https://api.nokotime.com/v2/project_groups/3768"
    },
    "minutes": 180,
    "billable_minutes": 120,
    "unbillable_minutes": 60,
    "invoiced_minutes": 120,
    "remaining_minutes": 630,
    "budgeted_minutes": 750,
    "import": {
      "id": 8910,
      "url": "https://api.nokotime.com/v2/imports/8910"
    },
    "invoices": [
      {
        "id": 12345678,
        "reference": "AA001",
        "invoice_date": "2013-07-09",
        "state": "unpaid",
        "total_amount": 189.33,
        "url": "https://api.nokotime.com/v2/invoices/12345678"
      }
    ],
    "participants": [
      {
        "id": 5538,
        "email": "john.test@test.com",
        "first_name": "John",
        "last_name": "Test",
        "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
        "url": "https://api.nokotime.com/v2/users/5538"
      }
    ],
    "entries": 0,
    "entries_url": "https://api.nokotime.com/v2/projects/37396/entries",
    "expenses": 0,
    "expenses_url": "https://api.nokotime.com/v2/projects/37396/expenses",
    "created_at": "2012-01-09T08:33:29Z",
    "updated_at": "2012-01-09T08:33:29Z",
    "merge_url": "https://api.nokotime.com/v2/projects/37396/merge",
    "archive_url": "https://api.nokotime.com/v2/projects/37396/archive",
    "unarchive_url": "https://api.nokotime.com/v2/projects/37396/unarchive"
  }
]

Get a single project

GET /projects/:id

Response

Status: 200 OK
{
  "id": 37396,
  "name": "Gear GmbH",
  "billing_increment": 10,
  "enabled": true,
  "billable": true,
  "color": "#ff9898",
  "url": "https://api.nokotime.com/v2/projects/37396",
  "group": {
    "id": 3768,
    "name": "Sprockets, Inc.",
    "url": "https://api.nokotime.com/v2/project_groups/3768"
  },
  "minutes": 180,
  "billable_minutes": 120,
  "unbillable_minutes": 60,
  "invoiced_minutes": 120,
  "remaining_minutes": 630,
  "budgeted_minutes": 750,
  "import": {
    "id": 8910,
    "url": "https://api.nokotime.com/v2/imports/8910"
  },
  "invoices": [
    {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": "https://api.nokotime.com/v2/invoices/12345678"
    }
  ],
  "participants": [
    {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.nokotime.com/v2/projects/37396/entries",
  "expenses": 0,
  "expenses_url": "https://api.nokotime.com/v2/projects/37396/expenses",
  "created_at": "2012-01-09T08:33:29Z",
  "updated_at": "2012-01-09T08:33:29Z",
  "merge_url": "https://api.nokotime.com/v2/projects/37396/merge",
  "archive_url": "https://api.nokotime.com/v2/projects/37396/archive",
  "unarchive_url": "https://api.nokotime.com/v2/projects/37396/unarchive"
}

Create a project

POST /projects/

Inputs

name
Required string
The name of the project
billable
Optional boolean
Whether the project is billable or unbillable. Defaults to true
project_group_id
Optional integer
The ID of the Project Group the project will be associated with.
billing_increment
Optional integer
The billing increment used by this project. The default value is the account’s default billing increment (which is 15 by default).
Accepted values: 1, 5, 6, 10, 15, 20, 30, 60
color
Optional string
The hexadecimal color code that will be used as the project’s color.
{
  "name": "Gear GmbH",
  "project_group_id": 3768,
  "billing_increment": 10,
  "color": "#ff9898"
}

Response

Status: 201 Created
Location: https://api.nokotime.com/v2/projects/1
{
  "id": 37396,
  "name": "Gear GmbH",
  "billing_increment": 10,
  "enabled": true,
  "billable": true,
  "color": "#ff9898",
  "url": "https://api.nokotime.com/v2/projects/37396",
  "group": {
    "id": 3768,
    "name": "Sprockets, Inc.",
    "url": "https://api.nokotime.com/v2/project_groups/3768"
  },
  "minutes": 180,
  "billable_minutes": 120,
  "unbillable_minutes": 60,
  "invoiced_minutes": 120,
  "remaining_minutes": 630,
  "budgeted_minutes": 750,
  "import": {
    "id": 8910,
    "url": "https://api.nokotime.com/v2/imports/8910"
  },
  "invoices": [
    {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": "https://api.nokotime.com/v2/invoices/12345678"
    }
  ],
  "participants": [
    {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.nokotime.com/v2/projects/37396/entries",
  "expenses": 0,
  "expenses_url": "https://api.nokotime.com/v2/projects/37396/expenses",
  "created_at": "2012-01-09T08:33:29Z",
  "updated_at": "2012-01-09T08:33:29Z",
  "merge_url": "https://api.nokotime.com/v2/projects/37396/merge",
  "archive_url": "https://api.nokotime.com/v2/projects/37396/archive",
  "unarchive_url": "https://api.nokotime.com/v2/projects/37396/unarchive"
}

Custom Error Codes

Get the entries for a project

GET /projects/:id/entries

Parameters

You can use the parameters specified in the Entry API’s List Action to further limit the results

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/projects/:id/entries?page=2>; rel="next",
 <https://api.nokotime.com/v2/projects/:id/entries?page=5>; rel="last"
[
  {
    "id": 1,
    "date": "2012-01-09",
    "user": {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    },
    "billable": true,
    "minutes": 60,
    "description": "noko",
    "project": {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.nokotime.com/v2/projects/37396"
    },
    "tags": [
      {
        "id": 249397,
        "name": "noko",
        "billable": true,
        "formatted_name": "#noko",
        "url": "https://api.nokotime.com/v2/tags/249397"
      }
    ],
    "source_url": "http://someapp.com/special/url/",
    "invoiced_at": "2012-01-10T08:33:29Z",
    "invoice": {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": "https://api.nokotime.com/v2/invoices/12345678"
    },
    "import": {
      "id": 8910,
      "url": "https://api.nokotime.com/v2/imports/8910"
    },
    "approved_at": "2012-01-10T08:33:29Z",
    "approved_by": {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    },
    "url": "https://api.nokotime.com/v2/entries/1711626",
    "invoiced_outside_of_noko_url": "https://api.nokotime.com/v2/entries/1711626/marked_as_invoiced",
    "approved_url": "https://api.nokotime.com/v2/entries/1711626/approved",
    "unapproved_url": "https://api.nokotime.com/v2/entries/1711626/unapproved",
    "created_at": "2012-01-09T08:33:29Z",
    "updated_at": "2012-01-09T08:33:29Z"
  }
]

Get the expenses for a project

GET /projects/:id/expenses

Parameters

You can use the parameters specified in the Expense API’s List Action to further limit the results

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/projects/:id/expenses?page=2>; rel="next",
 <https://api.nokotime.com/v2/projects/:id/expenses?page=5>; rel="last"
[
  {
    "id": 2233,
    "price": 14.55,
    "description": "new software",
    "taxable": true,
    "date": "2010-06-09",
    "project": {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.nokotime.com/v2/projects/37396"
    },
    "invoice": {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": "https://api.nokotime.com/v2/invoices/12345678"
    },
    "user": {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    },
    "url": "https://api.nokotime.com/v2/expense/2233",
    "created_at": "2010-06-09T20:44:57Z",
    "updated_at": "2010-06-09T20:44:57Z"
  }
]

Edit a project

PUT /projects/:id

Inputs

name
Optional string
The name of the project
project_group_id
Optional integer
The ID of the Project Group the project will be associated with.
billing_increment
Optional integer
The billing increment used by this project. Defaults to the account’s default billing increment (which is 15 by default).
Accepted values: 1, 5, 6, 10, 15, 20, 30, 60
color
Optional string
a hexadecimal color code for the project.
{
  "name": "Gear GmbH",
  "project_group_id": 3768,
  "billing_increment": 10,
  "color": "#ff9898"
}

Response

Status: 200 OK
{
  "id": 37396,
  "name": "Gear GmbH",
  "billing_increment": 10,
  "enabled": true,
  "billable": true,
  "color": "#ff9898",
  "url": "https://api.nokotime.com/v2/projects/37396",
  "group": {
    "id": 3768,
    "name": "Sprockets, Inc.",
    "url": "https://api.nokotime.com/v2/project_groups/3768"
  },
  "minutes": 180,
  "billable_minutes": 120,
  "unbillable_minutes": 60,
  "invoiced_minutes": 120,
  "remaining_minutes": 630,
  "budgeted_minutes": 750,
  "import": {
    "id": 8910,
    "url": "https://api.nokotime.com/v2/imports/8910"
  },
  "invoices": [
    {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": "https://api.nokotime.com/v2/invoices/12345678"
    }
  ],
  "participants": [
    {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.nokotime.com/v2/projects/37396/entries",
  "expenses": 0,
  "expenses_url": "https://api.nokotime.com/v2/projects/37396/expenses",
  "created_at": "2012-01-09T08:33:29Z",
  "updated_at": "2012-01-09T08:33:29Z",
  "merge_url": "https://api.nokotime.com/v2/projects/37396/merge",
  "archive_url": "https://api.nokotime.com/v2/projects/37396/archive",
  "unarchive_url": "https://api.nokotime.com/v2/projects/37396/unarchive"
}

Custom Error Codes

Merge a project into this project

Merge the project specified in the request body into this project. This will move all the project’s entries, expenses, and invoices into this project. The project will be deleted after the merge has completed. Note that projects cannot be merged if either project is archived. This action is permanent, so you cannot undo after you merge projects.

PUT /projects/:id/merge

Inputs

project_id
Required integer
the ID of the Project to merge into this project.

A diagram explaining the project merge action.

Response

Status: 204 No Content

Custom Error Codes

Delete a project

DELETE /projects/:id

Response

Status: 204 No Content

Custom Error Codes

A note about project deletion

A project cannot be deleted if there are any entries, invoices, or expenses associated with this project.

You can archive the project, which will flag the project as “archived” while keeping any entries, invoices, or expenses associated with this project.

For more information about how deleting and archiving a project works, please the API basics section on Deleting or Archiving Resources

Archive a project

PUT /projects/:id/archive

Response

Status: 204 No Content

Custom Error Codes

A note about project archiving

A project cannot be archived if there are no entries, invoices, or expenses associated with this project. Instead, you can only delete the project.

For more information about how deleting and archiving a project works, please the API basics section on Deleting or Archiving Resources

Unarchive a project

PUT /projects/:id/unarchive

Response

Status: 204 No Content

Archive multiple projects at once

PUT /projects/archive

Inputs

project_ids
Required array of integers: the IDs of the projects to be archived

Response

Status: 204 No Content

A note about projects that cannot be archived

Any projects are included in this request that cannot be archived will be ignored and will not affect the Response.

Unarchive multiple projects at once

PUT /projects/unarchive

Inputs

project_ids
Required array of integers: the IDs of the projects to be unarchived

Response

Status: 204 No Content

Delete multiple projects at once

PUT /projects/delete

Inputs

project_ids
Required array of integers: the IDs of the projects to be deleted

Response

Status: 204 No Content

A note about projects that cannot be deleted

Any projects are included in this request that cannot be deleted will be ignored and will not affect the Response.