Entries

List Entries

Get all entries, sorted by the most recent entry date.

GET /v2/entries

Parameters

Each parameter passed will filter the results, and parameters are chained (meaning that if you search by users and projects, it will only return entries from those users for those projects).

user_ids
Optional string
A comma-separated list of user IDs to filter by.
Example: user_ids=1,2,3
description
Optional string
Only entries containing this text in their description are returned.
Example: description=meeting
project_ids
Optional string
A comma-separated list of project IDs to filter by.
Example: project_ids=4,5,6
tag_ids
Optional string
A comma-separated list of tag IDs to filter by.
Example: tag_ids=7,8,9
tag_filter_type
Optional string
Indicates how to filter by tags.
Accepted values: and (default), combination of
invoice_ids
Optional string
A comma-separated list of invoice IDs to filter by.
Example: invoice_ids=1,2,3
import_ids
Optional string
A comma-separated list of import IDs to filter by.
Example: import_ids=4,5,6
from
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only entries from or after this date will be returned.
Example: from=2013-09-27
to
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only entries on or before this date will be returned.
Example: to=2013-09-27
invoiced_at_from
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only entries invoiced from or after this date will be returned.
Example: invoiced_at_from=2013-09-27
invoiced_at_to
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only entries invoiced on or before this date will be returned.
Example: invoiced_at_to=2013-09-27
updated_from
Optional string of a timestamp in ISO 8061 format YYYY-MM-DDTHH:MM:SSZ
Only entries updated from or after this timestamp will be returned.
Example: updated_from=2012-01-09T08:33:29Z
updated_to
Optional string of a timestamp in ISO 8061 format YYYY-MM-DDTHH:MM:SSZ
Only entries updated on or before this timestamp will be returned.
Example: updated_to=2012-01-09T08:33:29Z
billable
Optional boolean
true: only show billable entries
false: only shows unbillable entries
approved_at_from
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only entries approved from or after this date will be returned.
Example: approved_at_from=2013-09-27
approved_at_to
Optional string of a date in ISO 8061 format YYYY-MM-DD
Only entries approved on or before this date will be returned.
Example: approved_at_to=2013-09-27
approved_by_ids
Optional string
A comma-separated list of user IDs to filter by.
Only entries that have been approved by these users will be returned.
Example: approved_by_ids=1,2,3

Response

Status: 200 OK
Link: <https://api.letsfreckle.com/v2/entries?page=2>; rel="next",
 <https://api.letsfreckle.com/v2/entries?page=5>; rel="last"
[
  {
    "id": 1,
    "date": "2012-01-09",
    "user": {
      "id": 5538,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.letsfreckle.com/v2/users/5538"
    },
    "billable": true,
    "minutes": 60,
    "description": "freckle",
    "project": {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.letsfreckle.com/v2/projects/37396"
    },
    "tags": [
      {
        "id": 249397,
        "name": "freckle",
        "billable": true,
        "formatted_name": "#freckle",
        "url": "https://api.letsfreckle.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.letsfreckle.com/v2/invoices/12345678"
    },
    "import": {
      "id": 8910,
      "url": "https://api.letsfreckle.com/v2/imports/8910"
    },
    "approved_at": "2012-01-10T08:33:29Z",
    "approved_by": {
      "id": 5538,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.letsfreckle.com/v2/users/5538"
    },
    "url": "https://api.letsfreckle.com/v2/entries/1711626",
    "invoiced_outside_of_freckle_url": "https://api.letsfreckle.com/v2/entries/1711626/invoiced_outside_of_freckle",
    "approved_url": "https://api.letsfreckle.com/v2/entries/1711626/approved",
    "unapproved_url": "https://api.letsfreckle.com/v2/entries/1711626/unapproved",
    "created_at": "2012-01-09T08:33:29Z",
    "updated_at": "2012-01-09T08:33:29Z"
  }
]

Get a single Entry

GET /v2/entries/:id
Status: 200 OK
{
  "id": 1,
  "date": "2012-01-09",
  "user": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "billable": true,
  "minutes": 60,
  "description": "freckle",
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.letsfreckle.com/v2/projects/37396"
  },
  "tags": [
    {
      "id": 249397,
      "name": "freckle",
      "billable": true,
      "formatted_name": "#freckle",
      "url": "https://api.letsfreckle.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.letsfreckle.com/v2/invoices/12345678"
  },
  "import": {
    "id": 8910,
    "url": "https://api.letsfreckle.com/v2/imports/8910"
  },
  "approved_at": "2012-01-10T08:33:29Z",
  "approved_by": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "url": "https://api.letsfreckle.com/v2/entries/1711626",
  "invoiced_outside_of_freckle_url": "https://api.letsfreckle.com/v2/entries/1711626/invoiced_outside_of_freckle",
  "approved_url": "https://api.letsfreckle.com/v2/entries/1711626/approved",
  "unapproved_url": "https://api.letsfreckle.com/v2/entries/1711626/unapproved",
  "created_at": "2012-01-09T08:33:29Z",
  "updated_at": "2012-01-09T08:33:29Z"
}

Create an Entry

POST /v2/entries

Input

date
Required string of a date in ISO 8061 format YYY-MM-DD
The date of the time entry.
user_id
Optional integer
The ID of the user who logged this time entry. If no value is provided, the authenticated user will be used.
minutes
Required integer
The number of minutes logged in this time entry. This number will automatically be rounded up based on the project’s “billing_increment” settings.
description
Optional string
The description of the time entry. Any tags or hashtags will be automatically parsed.
project_id
Optional integer
The ID of the project this time entry is logged under. If no value is provided, this time entry will not be logged under any project.
project_name
Optional string
The name of the project this time entry is logged under. If no value is provided, this time entry will not be logged under any project.
This value is only used if no value is provided for project_id.
If a project with this name does not exist yet, it will automatically be created with this entry.
source_url
Optional string
A URL that corresponds to the work completed in this time entry. Some Examples Include:
  • the URL to a client’s website.
{
  "date": "2012-01-09",
  "user_id": 5538,
  "minutes": 60,
  "description": "freckle",
  "project_id": 37396,
  "project_name": "Gear GmbH",
  "source_url": "http://someapp.com/special/url/"
}

Reponse

Status: 201 Created
Location: https://api.letsfreckle.com/v2/entries/1
{
  "id": 1,
  "date": "2012-01-09",
  "user": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "billable": true,
  "minutes": 60,
  "description": "freckle",
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.letsfreckle.com/v2/projects/37396"
  },
  "tags": [
    {
      "id": 249397,
      "name": "freckle",
      "billable": true,
      "formatted_name": "#freckle",
      "url": "https://api.letsfreckle.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.letsfreckle.com/v2/invoices/12345678"
  },
  "import": {
    "id": 8910,
    "url": "https://api.letsfreckle.com/v2/imports/8910"
  },
  "approved_at": "2012-01-10T08:33:29Z",
  "approved_by": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "url": "https://api.letsfreckle.com/v2/entries/1711626",
  "invoiced_outside_of_freckle_url": "https://api.letsfreckle.com/v2/entries/1711626/invoiced_outside_of_freckle",
  "approved_url": "https://api.letsfreckle.com/v2/entries/1711626/approved",
  "unapproved_url": "https://api.letsfreckle.com/v2/entries/1711626/unapproved",
  "created_at": "2012-01-09T08:33:29Z",
  "updated_at": "2012-01-09T08:33:29Z"
}

Custom Error Codes

Edit an Entry

PUT /v2/entries/:id

Input

date
Optional string of a date in ISO 8061 format YYY-MM-DD
the date of the time entry.
user_id
Optional integer
The ID of the user who logged this time entry. If no value is provided, the user will not be changed.
minutes
Optional integer
The number of minutes logged in this time entry. This number will automatically be rounded up based on the project’s “billing_increment” settings. If no value is provided, then the entry will have 0 minutes.
description
Optional string
The description of the time entry. Any tags or hashtags will be automatically parsed.
project_id
Optional integer
The ID of the project this time entry is logged under. If no value is provided, the project will not be changed.
project_name
Optional string
The name of the project this time entry is logged under. If no value is provided, the project will not be changed.
This value is only used if no value is provided for project_id.
If a project with this name does not exist yet, it will automatically be created with this entry.
source_url
Optional string
A URL that corresponds to the work completed in this time entry. Some Examples Include:
  • the URL to a client’s website.
{
  "date": "2012-01-09",
  "user_id": 5538,
  "minutes": 60,
  "description": "freckle",
  "project_id": 37396,
  "project_name": "Gear GmbH",
  "source_url": "http://someapp.com/special/url/"
}

Response

Status: 200 OK
{
  "id": 1,
  "date": "2012-01-09",
  "user": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "billable": true,
  "minutes": 60,
  "description": "freckle",
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.letsfreckle.com/v2/projects/37396"
  },
  "tags": [
    {
      "id": 249397,
      "name": "freckle",
      "billable": true,
      "formatted_name": "#freckle",
      "url": "https://api.letsfreckle.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.letsfreckle.com/v2/invoices/12345678"
  },
  "import": {
    "id": 8910,
    "url": "https://api.letsfreckle.com/v2/imports/8910"
  },
  "approved_at": "2012-01-10T08:33:29Z",
  "approved_by": {
    "id": 5538,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.letsfreckle.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.letsfreckle.com/v2/users/5538"
  },
  "url": "https://api.letsfreckle.com/v2/entries/1711626",
  "invoiced_outside_of_freckle_url": "https://api.letsfreckle.com/v2/entries/1711626/invoiced_outside_of_freckle",
  "approved_url": "https://api.letsfreckle.com/v2/entries/1711626/approved",
  "unapproved_url": "https://api.letsfreckle.com/v2/entries/1711626/unapproved",
  "created_at": "2012-01-09T08:33:29Z",
  "updated_at": "2012-01-09T08:33:29Z"
}

Custom Error Codes

Mark Entry as invoiced outside of Freckle

Update the Entry so that is recognized as being invoiced outside of Freckle by providing the date the Entry was invoiced.

If the entry has already been marked as invoiced outside of freckle, this action modifies the invoiced_at date for the entry.

PUT /v2/entries/:id/invoiced_outside_of_freckle

Input

date
Required string of a date in ISO 8061 format YYYY-MM-DD
The date the time entry was invoiced outside of Freckle.

Response

Status: 204 No Content

Custom Error Codes

The following Custom Error codes can be returned for this action:

Mark multiple Entries as invoiced outside of Freckle

Update the Entries provided so that they are recognized as being invoiced outside of Freckle by providing the date the Entries was invoiced.

If an entry has already been marked as invoiced outside of Freckle, this action modifies the invoiced_at date for that entry.

PUT /v2/entries/invoiced_outside_of_freckle

Input

entry_ids
Required array of integers
The IDs of the entries that will be marked as invoiced outside of Freckle.
date
Required string of a date in ISO 8061 format YYYY-MM-DD
The date the time entry was invoiced outside of Freckle.

Response

Status: 204 No Content

A note about Entries that cannot be marked as invoiced outside of Freckle

Any entries that are included in this request that cannot be marked as invoiced outside of Freckle will be ignored and will not affect the Response.

Mark Entry as approved

Mark the Entry as “approved” in Freckle. Approved entries cannot be edited or deleted.

PUT /v2/entries/:id/approved

Input

approved_at
Optional string of a timestamp in ISO 8061 format YYYY-MM-DDTHH:MM:SSZ
The timestamp for when the entry was approved. If no value is provided, the current time will be used.

Response

Status: 204 No Content

Custom Error Codes

The following Custom Error codes can be returned for this action:

Mark multiple Entries as approved

Mark the Entries provided as “approved” in Freckle. Approved entries cannot be edited or deleted.

PUT /v2/entries/approved

Input

entry_ids
Required array of integers
The IDs of the entries that will be marked as approved.
approved_at
Optional string of a timestamp in ISO 8061 format YYYY-MM-DDTHH:MM:SSZ
The timestamp for when the entry was approved. If no value is provided, the current time will be used.

Response

Status: 204 No Content

A note about Entries that cannot be marked as approved

Any entries that are included in this request that cannot be marked as approved will be ignored and will not affect the Response.

Mark Entry as unapproved

Mark the Entry as “unapproved” in Freckle. Unapproved entries can be edited or deleted.

PUT /v2/entries/:id/unapproved

Response

Status: 204 No Content

Custom Error Codes

The following Custom Error codes can be returned for this action:

Mark multiple Entries as unapproved

Mark the Entries provided as “unapproved” in Freckle. Unapproved entries can be edited or deleted.

PUT /v2/entries/unapproved

Input

entry_ids
Required array of integers
The IDs of the entries that will be marked as approved.

Response

Status: 204 No Content

A note about Entries that cannot be marked as unapproved

Any entries that are included in this request that cannot be marked as unapproved will be ignored and will not affect the Response.

Delete an Entry

DELETE /v2/entries/:id

Response

Status: 204 No Content

A note about entry deletion

An entry cannot be deleted if it has been invoiced, is associated with an archived project, or is approved and locked. In this case, response will include detailed information about why the entry couldn’t be deleted.

Custom Error Codes

The following Custom Error codes can be returned for this action: