Tag

List all Tags

GET /tags/

Parameters

name
Optional string
Only tags containing this string will be returned.
Example: name=meeting
billable
Optional boolean
true: return all billable tags.
false: returns all unbillable tags.

Response

Status: 200 OK
Link: <https://api.letsfreckle.com/v2/tags?page=2>; rel="next",
 <https://api.letsfreckle.com/v2/tags?page=5>; rel="last"
{
  "id": 249397,
  "name": "freckle",
  "billable": true,
  "formatted_name": "#freckle",
  "url": "https://api.letsfreckle.com/v2/tags/249397",
  "import": {
    "id": 8910,
    "url": "https://api.letsfreckle.com/v2/imports/8910"
  },
  "entries": 0,
  "entries_url": "https://api.letsfreckle.com/v2/tags/55629/entries",
  "merge_url": "https://api.letsfreckle.com/v2/tags/55629/merge",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Create multiple Tags at once

POST /tags/

Inputs

names
Required array of string
The names of the tags to create. Adding a “*” at the end of a string indicates that the tag is unbillable.

Response

Status: 201 Created
[
  {
    "id": 249397,
    "name": "freckle",
    "billable": true,
    "formatted_name": "#freckle",
    "url": "https://api.letsfreckle.com/v2/tags/249397",
    "import": {
      "id": 8910,
      "url": "https://api.letsfreckle.com/v2/imports/8910"
    },
    "entries": 0,
    "entries_url": "https://api.letsfreckle.com/v2/tags/55629/entries",
    "merge_url": "https://api.letsfreckle.com/v2/tags/55629/merge",
    "created_at": "2010-06-09T20:44:57Z",
    "updated_at": "2010-06-09T20:44:57Z"
  }
]

A note about tag creation

Any tag that cannot be created or already exists will be ignored and not affect the response

Get a single tag

GET /tags/:id

Response

Status: 200 OK
{
  "id": 249397,
  "name": "freckle",
  "billable": true,
  "formatted_name": "#freckle",
  "url": "https://api.letsfreckle.com/v2/tags/249397",
  "import": {
    "id": 8910,
    "url": "https://api.letsfreckle.com/v2/imports/8910"
  },
  "entries": 0,
  "entries_url": "https://api.letsfreckle.com/v2/tags/55629/entries",
  "merge_url": "https://api.letsfreckle.com/v2/tags/55629/merge",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Get the entries for a tag

GET /tags/: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.letsfreckle.com/v2/tags/:id/entries?page=2>; rel="next",
 <https://api.letsfreckle.com/v2/tags/:id/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"
}

Edit a Tag

PUT /tags/:id

Inputs

name
Optional string
The name for the tag. Adding a “*” at the end of the string indicates that the tag is unbillable.

Response

Status: 200 OK
{
  "id": 249397,
  "name": "freckle",
  "billable": true,
  "formatted_name": "#freckle",
  "url": "https://api.letsfreckle.com/v2/tags/249397",
  "import": {
    "id": 8910,
    "url": "https://api.letsfreckle.com/v2/imports/8910"
  },
  "entries": 0,
  "entries_url": "https://api.letsfreckle.com/v2/tags/55629/entries",
  "merge_url": "https://api.letsfreckle.com/v2/tags/55629/merge",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Custom Error Codes

Merge a Tag into this Tag

When one tag is merged into another, the entries associated with the tag are associated with the new tag, and any instances of the old tags are replaced with the new tags in the Entry Description. This action is permanent, so you cannot undo after you merge tags.

PUT /tags/:id/merge

Inputs

tag_id
Required integer
The ID of the tag to merge into this tag.

Response

Status: 204 No Content

Custom Error Codes

Delete a Tag

When a tag is deleted, the entries associated with that tag are not deleted. Instead, their descriptions are updated so that the tag’s text becomes part of the description.

DELETE /tags/:id

Response

Status: 204 No Content

Custom Error Codes

Delete Multiple Tags at once

When a tag is deleted, the entries associated with that tag are not deleted. Instead, their descriptions are updated so that the tag’s text becomes part of the description.

PUT /tags/delete

Inputs

tag_ids
Required array of integers
The IDs of the tags to delete. If no IDs are provided, then no tags are deleted.

Response

Status: 204 No Content

A note about Tags that cannot be deleted

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