User

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

List Users
Get a single user
Get a User’s Entries
Get a User’s Expenses
Create a User
Edit a User
Reactivate a Deactivated User
Give a User Access to Projects
Revoke a User’s Access to Projects
Revoke a user’s access to all projects
Delete a User
Deactivate a 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.nokotime.com/v2/users?page=2>; rel="next",
 <https://api.nokotime.com/v2/users?page=5>; rel="last"

[
  {
    "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",
    "state": "active",
    "role": "leader",
    "teams": [
      {
        "id": 9283,
        "name": "R&D",
        "url": "https://api.nokotime.com/v2/teams/9283"
      }
    ],
    "entries": 0,
    "entries_url": "https://api.nokotime.com/v2/users/5538/entries",
    "expenses": 0,
    "expenses_url": "https://api.nokotime.com/v2/users/5538/expenses",
    "give_access_to_project_url": "https://api.nokotime.com/v2/users/5538/give_access_to_projects",
    "revoke_access_to_project_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_projects",
    "revoke_access_to_all_projects_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_all_projects",
    "activate_url": "https://api.nokotime.com/v2/users/5538/activate",
    "deactivate_url": "https://api.nokotime.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": "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",
  "state": "active",
  "role": "leader",
  "teams": [
    {
      "id": 9283,
      "name": "R&D",
      "url": "https://api.nokotime.com/v2/teams/9283"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.nokotime.com/v2/users/5538/entries",
  "expenses": 0,
  "expenses_url": "https://api.nokotime.com/v2/users/5538/expenses",
  "give_access_to_project_url": "https://api.nokotime.com/v2/users/5538/give_access_to_projects",
  "revoke_access_to_project_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_projects",
  "revoke_access_to_all_projects_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_all_projects",
  "activate_url": "https://api.nokotime.com/v2/users/5538/activate",
  "deactivate_url": "https://api.nokotime.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.nokotime.com/v2/users/:id/entries?page=2>; rel="next",
 <https://api.nokotime.com/v2/users/: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 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.nokotime.com/v2/users/:id/expenses?page=2>; rel="next",
 <https://api.nokotime.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.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"
  }
]

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 Noko 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.nokotime.com/v2/users/1

{
  "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",
  "state": "active",
  "role": "leader",
  "teams": [
    {
      "id": 9283,
      "name": "R&D",
      "url": "https://api.nokotime.com/v2/teams/9283"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.nokotime.com/v2/users/5538/entries",
  "expenses": 0,
  "expenses_url": "https://api.nokotime.com/v2/users/5538/expenses",
  "give_access_to_project_url": "https://api.nokotime.com/v2/users/5538/give_access_to_projects",
  "revoke_access_to_project_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_projects",
  "revoke_access_to_all_projects_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_all_projects",
  "activate_url": "https://api.nokotime.com/v2/users/5538/activate",
  "deactivate_url": "https://api.nokotime.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:

reached_user_limit: the account has reached the maximum number of active users available for the current plan. The account owner will have to upgrade their account.

Edit a User

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": "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",
  "state": "active",
  "role": "leader",
  "teams": [
    {
      "id": 9283,
      "name": "R&D",
      "url": "https://api.nokotime.com/v2/teams/9283"
    }
  ],
  "entries": 0,
  "entries_url": "https://api.nokotime.com/v2/users/5538/entries",
  "expenses": 0,
  "expenses_url": "https://api.nokotime.com/v2/users/5538/expenses",
  "give_access_to_project_url": "https://api.nokotime.com/v2/users/5538/give_access_to_projects",
  "revoke_access_to_project_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_projects",
  "revoke_access_to_all_projects_url": "https://api.nokotime.com/v2/users/5538/revoke_access_to_all_projects",
  "activate_url": "https://api.nokotime.com/v2/users/5538/activate",
  "deactivate_url": "https://api.nokotime.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:

deactivated: The user is deactivated, and therefore cannot be edited until they are reactivated.
authenticated_user: Authenticated users cannot change certain properties about themselves.

Reactivate a Deactivated User

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

PUT /users/:id/activate

Response

Status: 204 No Content

Custom Error Codes

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

not_deactivated: The user is not deactivated, and therefore cannot be reactivated.
reached_user_limit: the account has reached the maximum number of active users available for the current plan. The account owner will have to upgrade their account.

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:

deactivated: The user is deactivated, and therefore cannot be given access to any projects.
authenticated_user: Authenticated users cannot change their project access rules.

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:

can_access_all_projects: The user is has access all the projects in this account, and cannot be prevented from accessing specific projects.
deactivated: The user is deactivated, and therefore cannot be modified.
authenticated_user: Authenticated users cannot change their project access rules.

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:

can_access_all_projects: The user is has access all the projects in this account, and cannot be prevented from accessing specific projects.
deactivated: The user is deactivated, and therefore cannot be modified.
authenticated_user: Authenticated users cannot change their project access rules.

Delete a User

DELETE /users/:id

Response

Status: 204 No Content

Custom Error Codes

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

account_owner: Account owners cannot be deleted
authenticated_user: Authenticated users cannot delete themselves.
not_deletable: the User cannot be deleted because they have entries

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

PUT /users/:id/deactivate

Response

Status: 204 No Content

Custom Error Codes

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

account_owner: Account owners cannot be deactivated
authenticated_user: Authenticated users cannot deactivate themselves.
deletable: the user should be deleted because they do not have any entries

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

Topics

Resources

Webhooks

Broadcasts

Account Management

User

List Users

Parameters

Response

Get a single user

Response

Get a User’s Entries

Parameters

Response

Get a User’s Expenses

Parameters

Response

Create a User

Inputs

Response

Custom Error Codes

Edit a User

Inputs

Response

Custom Error Codes

Reactivate a Deactivated User

Response

Custom Error Codes

Give a User Access to Projects

Inputs

Response

Custom Error Codes

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

Revoke a User’s Access to Projects

Inputs

Response

Custom Error Codes

Revoke a user’s access to all projects

Response

Custom Error Codes

Delete a User

Response

Custom Error Codes

A note about user deletion

Deactivate a User

Response

Custom Error Codes

A note about user deactivation

About Noko

Us & our company

Docs

You & your account