User

List Users

GET /users/

Parameters

name
Optional string
Only users with this string in their name are returned.
Example: name=John
email
Optional string
Only users with this string in their email address are returned.
Example: email=mary
role
Optional string
Only users with this role will be returned. Accepted values are:
  • supervisor
  • leader
  • coworker
  • contractor
state
Optional string
Only users with this state will be returned. Accepted values are:
  • disabled
  • pending
  • active
  • suspended

Response

Status: 200 OK
Link: <https://api.letsfreckle.com/v2/users?page=2>; rel="next",
 <https://api.letsfreckle.com/v2/users?page=5>; rel="last"
[
  {
    "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",
    "state": "active",
    "role": "leader",
    "teams": [
      {
        "id": 9283,
        "name": "R&D",
        "url": "https://api.letsfreckle.com/v2/teams/9283"
      }
    ],
    "entries": 0,
    "entries_url": "https://api.letsfreckle.com/v2/users/5538/entries",
    "expenses": 0,
    "expenses_url": "https://api.letsfreckle.com/v2/users/5538/expenses",
    "give_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/give_access_to_projects",
    "revoke_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_projects",
    "revoke_access_to_all_projects_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_all_projects",
    "activate_url": "https://api.letsfreckle.com/v2/users/5538/activate",
    "deactivate_url": "https://api.letsfreckle.com/v2/users/5538/deactivate",
    "created_at": "2010-06-09T20:44:57Z",
    "updated_at": "2010-06-09T20:44:57Z"
  }
]

Get a single user

GET /users/:id

Response

Status: 200 OK
{
  "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",
  "state": "active",
  "role": "leader",
  "teams": [
    {
      "id": 9283,
      "name": "R&D",
      "url": "https://api.letsfreckle.com/v2/teams/9283"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.letsfreckle.com/v2/users/5538/entries",
  "expenses": 0,
  "expenses_url": "https://api.letsfreckle.com/v2/users/5538/expenses",
  "give_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/give_access_to_projects",
  "revoke_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_projects",
  "revoke_access_to_all_projects_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_all_projects",
  "activate_url": "https://api.letsfreckle.com/v2/users/5538/activate",
  "deactivate_url": "https://api.letsfreckle.com/v2/users/5538/deactivate",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Get a User’s Entries

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

Get a User’s Expenses

GET /users/: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.letsfreckle.com/v2/users/:id/expenses?page=2>; rel="next",
 <https://api.letsfreckle.com/v2/users/: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.letsfreckle.com/v2/projects/37396"
    },
    "invoice": {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": "https://api.letsfreckle.com/v2/invoices/12345678"
    },
    "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"
    },
    "url": "https://api.letsfreckle.com/v2/expense/2233",
    "created_at": "2010-06-09T20:44:57Z",
    "updated_at": "2010-06-09T20:44:57Z"
  }
]

Create a User

For accounts with subscriptions that include per-user pricing, calling this action may change the billing amount total for the next monthly billing cycle and/or change the next billing date if there is an active prepayment for this Freckle account.

POST /users/

Inputs

email
Required string
The email address of the user.
first name
Optional string
The first name of the user.
last name
Optional string
The last name of the user.
role
Optional string
The user’s role. Accepted values are:
  • supervisor
  • leader (default)
  • coworker
  • contractor

Response

Status: 201 Created
Location: https://api.letsfreckle.com/v2/users/1
{
  "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",
  "state": "active",
  "role": "leader",
  "teams": [
    {
      "id": 9283,
      "name": "R&D",
      "url": "https://api.letsfreckle.com/v2/teams/9283"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.letsfreckle.com/v2/users/5538/entries",
  "expenses": 0,
  "expenses_url": "https://api.letsfreckle.com/v2/users/5538/expenses",
  "give_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/give_access_to_projects",
  "revoke_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_projects",
  "revoke_access_to_all_projects_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_all_projects",
  "activate_url": "https://api.letsfreckle.com/v2/users/5538/activate",
  "deactivate_url": "https://api.letsfreckle.com/v2/users/5538/deactivate",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Custom Error Codes

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

Edit a User

For accounts with subscriptions that include per-user pricing, calling this action may change the billing amount total for the next monthly billing cycle and/or change the next billing date if there is an active prepayment for this Freckle account.

PUT /users/:id

Inputs

first name
Optional string
The first name of the user
last name
Optional string
The last name of the user
role
Optional string
The user’s role. Accepted values are:
  • supervisor
  • leader
  • coworker
  • contractor

Response

Status: 200 OK
{
  "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",
  "state": "active",
  "role": "leader",
  "teams": [
    {
      "id": 9283,
      "name": "R&D",
      "url": "https://api.letsfreckle.com/v2/teams/9283"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.letsfreckle.com/v2/users/5538/entries",
  "expenses": 0,
  "expenses_url": "https://api.letsfreckle.com/v2/users/5538/expenses",
  "give_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/give_access_to_projects",
  "revoke_access_to_project_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_projects",
  "revoke_access_to_all_projects_url": "https://api.letsfreckle.com/v2/users/5538/revoke_access_to_all_projects",
  "activate_url": "https://api.letsfreckle.com/v2/users/5538/activate",
  "deactivate_url": "https://api.letsfreckle.com/v2/users/5538/deactivate",
  "created_at": "2010-06-09T20:44:57Z",
  "updated_at": "2010-06-09T20:44:57Z"
}

Custom Error Codes

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

Reactivate a Deactivated User

This action reactivates a previously deactivated user, which allows the user to start using Freckle again.

For accounts with subscriptions that include per-user pricing, calling this action may change the billing amount total for the next monthly billing cycle and/or change the next billing date if there is an active prepayment for this Freckle account.

PUT /users/:id/activate

Response

Status: 204 No Content

Custom Error Codes

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

Give a User Access to Projects

Currently, only freelancers are affected by project access rules.

Giving a User Access to a project allows them to view and create entries and expenses for the project. Any projects the user already has access to are ignored.

PUT /users/:id/give_access_to_projects

Inputs

project_ids
Required array of integers: the IDs of the projects to give a User access to.

Response

Status: 204 No Content

Custom Error Codes

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

A note about projects that the user cannot be given access to

Any projects are included in this request that the user cannot be given access to will be ignored and will not affect the Response.

Revoke a User’s Access to Projects

Currently, only freelancers are affected by project access rules.

Revoking a User’s access to a project prevents them from viewing the entries and expenses for the project. Note that the user’s entries and expenses logged for the project are not deleted. Any projects that the user does not have access to are ignored.

PUT /users/:id/revoke_access_to_projects

Inputs

project_ids
Required array of integers: the IDs of the projects to revoke a User’s access to.

Response

Status: 204 No Content

Custom Error Codes

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

Revoke a user’s access to all projects

Currently, only freelancers are affected by project access rules.
PUT /users/:id/revoke_access_to_all_projects

Response

Status: 204 No Content

Custom Error Codes

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

Delete a User

For accounts with subscriptions that include per-user pricing, calling this action may change the billing amount total for the next monthly billing cycle and/or change the next billing date if there is an active prepayment for this Freckle account.

DELETE /users/:id

Response

Status: 204 No Content

Custom Error Codes

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

A note about user deletion

A user cannot be deleted if there are any entries associated with this user.

You can deactivate the user, which will remove this user from the list of active users and increment the number of available users available until the account limit is reached.

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

Deactivate a User

For accounts with subscriptions that include per-user pricing, calling this action may change the billing amount total for the next monthly billing cycle and/or change the next billing date if there is an active prepayment for this Freckle account.

PUT /users/:id/deactivate

Response

Status: 204 No Content

Custom Error Codes

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

A note about user deactivation

A user cannot be deactivated if there are no entries associated with this user. Instead, you can only delete the user.

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