User Resource

Readable attributes

id	integer	Unique ID of the User.
account_id	integer	ID of the Account user belongs to.
login	string	Username. Unique per Account.
email	string	Email address. Unique per account.
name	string	Full name.
fist_name	string	First name.
last_name	string	Last name.
owner	boolean	True if User has created the Account initially.
admin	boolean	True if has admin privileges in the Account.
timezone	string	User’s preferred time zone. If not specified, Account’s time zone is used by default.
updated_at	datetime	Time when the User was last updated.
created_at	datetime	Time when the User was first added to the system.

Writable attributes

login	string	Writable only on create. Always required and must be unique in the Account.
email	string	Required on create.
name	string	Required on create.
password	string	Required on create.
admin	boolean	Optional.
timezone	string	Optional.

Find All Users

Admin privileges required for this API method.

This method support optional pagination that is disabled by default. Simply pass the page parameter to turn it on.

Optional GET parameters:

page (integer) — page number for pagination;
per_page (integer) — number of elements per page (default 30, maximum 50).

json http-request

GET /api/users.json

Click to expand…

json http-response

[
  {
    "user": {
      "owner": true,
      "created_at": "2011/07/20 23:11:17 +0800",
      "updated_at": "2011/10/05 14:14:58 +0800",
      "admin": false,
      "account_id": 2,
      "timezone": "Krasnoyarsk",
      "id": 2,
      "last_name": "Sabanin",
      "login": "ilya",
      "first_name": "Ilya",
      "name": "Ilya Sabanin",
      "email": "doesntexist@example.com"
    }
  }
]

xml http-request

GET /api/users.xml

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <account-id type="integer">44253</account-id>
    <admin type="boolean">true</admin>
    <owner type="boolean">false</owner>
    <created-at type="datetime">
      2007-05-16T23:52:31Z
    </created-at>
    <email>email@example.com</email>
    <first-name>Dima</first-name>
    <name>Dima Sabanin</name>
    <id type="integer">624622</id>
    <last-name>Sabanin</last-name>
    <login>sdmitry</login>
    <timezone>Krasnoyarsk</timezone>
    <updated-at type="datetime">
      2009-04-20T19:05:16Z
    </updated-at>
  </user>
  <user>
    <account-id type="integer">56346</account-id>
    <admin type="boolean" nil="true"></admin>
    <owner type="boolean">false</owner>
    <created-at type="datetime">
      2007-05-17T00:55:39Z
    </created-at>
    <email>fakeemail_2@nowhere.example.com</email>
    <first-name>Ilya</first-name>
    <name>Ilya Sabanin</name>
    <id type="integer">2349</id>
    <last-name>Sabanin</last-name>
    <login>ilya</login>
    <timezone nil="true"></timezone>
    <updated-at type="datetime">
      2009-04-20T19:05:18Z
    </updated-at>
  </user>
</users>

Find User

Admin privileges required for this API method.

json http-request

GET /api/users/{USER_ID}.json

Click to expand…

json http-response

{
  "user": {
    "owner": true,
    "created_at": "2011/07/20 23:11:17 +0800",
    "updated_at": "2011/10/05 14:14:58 +0800",
    "admin": false,
    "account_id": 2,
    "timezone": "Krasnoyarsk",
    "id": 2,
    "last_name": "Sabanin",
    "login": "ilya",
    "first_name": "Ilya",
    "name": "Ilya Sabanin",
    "email": "doesntexist@example.com"
  }
}

xml http-request

GET /api/users/{USER_ID}.xml

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <account-id type="integer">44253</account-id>
  <admin type="boolean">true</admin>
  <owner type="boolean">false</owner>
  <created-at type="datetime">
    2007-05-16T23:52:31Z
  </created-at>
  <email>email@example.com</email>
  <first-name>Dima</first-name>
  <name>Dima Sabanin</name>
  <id type="integer">624622</id>
  <last-name>Sabanin</last-name>
  <login>sdmitry</login>
  <timezone>Krasnoyarsk</timezone>
  <updated-at type="datetime">
    2009-04-20T19:05:16Z
  </updated-at>
</user>

Find User for Current Session

Returns currently logged in user.

json http-request

GET /api/users/current.json

Click to expand…

json http-response

{
  "user": {
    "owner": true,
    "created_at": "2011/07/20 23:11:17 +0800",
    "updated_at": "2011/10/05 14:14:58 +0800",
    "admin": false,
    "account_id": 2,
    "timezone": "Krasnoyarsk",
    "id": 2,
    "last_name": "Sabanin",
    "login": "ilya",
    "first_name": "Ilya",
    "name": "Ilya Sabanin",
    "email": "doesntexist@example.com"
  }
}

xml http-request

GET /api/users/current.xml

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <account-id type="integer">44253</account-id>
  <admin type="boolean">true</admin>
  <owner type="boolean">false</owner>
  <created-at type="datetime">
    2007-05-16T23:52:31Z
  </created-at>
  <email>email@example.com</email>
  <first-name>Dima</first-name>
  <name>Dima Sabanin</name>
  <id type="integer">624622</id>
  <last-name>Sabanin</last-name>
  <login>sdmitry</login>
  <timezone>Krasnoyarsk</timezone>
  <updated-at type="datetime">
    2009-04-20T19:05:16Z
  </updated-at>
</user>

Create User

Admin privileges required for this API method.

See a list of writable attributes at the top of the page.

json http-request

POST /api/users.json
{
  "user": {
    "admin": true,
    "timezone": "Philadelphia",
    "name": "John Doe",
    "login": "john",
    "email": "john@example.com",
    "password": "12345"
  }
}

Click to expand…

json http-response

{
  "user": {
    "owner": false,
    "created_at": "2011/07/20 23:11:17 +0800",
    "updated_at": "2011/10/05 14:14:58 +0800",
    "admin": true,
    "account_id": 2,
    "timezone": "Philadelphia",
    "id": 243,
    "last_name": "Doe",
    "login": "john",
    "first_name": "John",
    "name": "John Doe",
    "email": "john@example.com"
  }
}

--OR IF INVALID--

{
  "errors": ["Login can't be blank"]
}

xml http-request

POST /api/users.xml
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <login>ilya</login>
  <email>ilya@wildbit.com</email>
  <name>Ilya Sabanin</name>
  <password>12345</password>
</user>

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <account-id type="integer">44253</account-id>
  <admin type="boolean">false</admin>
  <owner type="boolean">false</owner>
  <created-at type="datetime">
    2010-10-16T23:52:31Z
  </created-at>
  <email>ilya@wildbit.com</email>
  <first-name>Ilya</first-name>
  <id type="integer">342544</id>
  <last-name>Sabanin</last-name>
  <name>Ilya Sabanin</name>
  <login>ilya</login>
  <timezone></timezone>
  <updated-at type="datetime">
    2010-10-16T23:52:31Z
  </updated-at>
</user>

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Login can't be blank</error>
</errors>

Update User

Admin privileges required for this API method.

See a list of writable attributes at the top of the page.

json http-request

PUT /api/users/{USER_ID}.json
{
  "user": {
    "timezone": "Eastern Time (US & Canada)"
  }
}

Click to expand…

json http-response

{
  "user": {
    "owner": false,
    "created_at": "2011/07/20 23:11:17 +0800",
    "updated_at": "2011/10/05 14:14:58 +0800",
    "admin": true,
    "account_id": 2,
    "timezone": "Eastern Time (US & Canada)",
    "id": 243,
    "last_name": "Doe",
    "login": "john",
    "first_name": "John",
    "name" => 'John Doe'
    "email": "john@example.com"
  }
}

--OR IF INVALID--

{
  "errors": ["timezone is blabla"]
}

xml http-request

PUT /api/users/{USER_ID}.xml
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <email>new-nifty-email-address@wildbit.com</email>
</user>

Click to expand…

xml http-response

HEAD 200 OK

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Email is already taken.</error>
</errors>

Delete User

Admin privileges required for this API method.

You can not delete account owner.

json http-request

DELETE /api/users/{USER_ID}.json

Click to expand…

json http-response

HEAD 200 OK

--OR IF INVALID--

{
  "errors": ["error message"]
}

xml http-request

DELETE /api/users/{USER_ID}.xml

Click to expand…

xml http-response

HEAD 200 OK

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>You can not delete account owner.</error>
</errors>