Your account must have the "client" classification enabled to view clients. Administrators can enable this classification using the web interface.

Client Managers can view, create, update and delete clients. Other users can only view clients associated with their assigned projects (see Project Assignments).

Clients containing projects associated with time entries can not be deleted. Consider making them inactive instead.

Show

Request

GET /clients/#{client-id}.xml

Optional parameters

Specify include=projects or include=projects,tasks to include related projects or projects and tasks. For example:

GET /clients/#{client-id}.xml?include=projects,tasks

Response

Status: 200 OK

<client>
  <id type="integer">21</id>
  <name>Munch Museum</name>
  <active type="boolean">true</active>
  <code nil="true"/>
  <description nil="true"/>
  <url nil="true"/>
  <created-at type="datetime">2007-03-30T20:28:40Z</created-at>
  <updated-at type="datetime">2007-12-20T06:55:23Z</updated-at>
  <!-- if include=projects -->
  <projects total="2" end="2" start="1">
    <project>
      ...
    </project>
    ...
  </projects>
</client>

List

Request

All clients:

GET /clients.xml

All active clients:

GET /clients/active.xml

All inactive clients:

GET /clients/inactive.xml

Clients associated with the current user via project assignments:

GET /clients/my_assignments.xml

Clients associated with the current user via active project assignments:

GET /clients/my_active_assignments.xml

Clients associated with the current user via inactive project assignments:

GET /clients/my_inactive_assignments.xml

Optional parameters

Specify start and end to request a specific range of items. For example:

GET /clients.xml?start=1&end=4

Specify include=projects or include=projects,tasks to include related projects or projects and tasks with each client. For example:

GET /clients.xml?include=projects,tasks

Response

Status: 200 OK

<clients total="4" end="4" start="1">
  <client>
    ...
  </client>
  ...
</clients>

Create

Request

POST /clients.xml

Include the following data with your request:

<client>
  <!-- name (REQUIRED) -->
  <name>ABC Corp</name>
  <!-- active (optional boolean, default = true) -->
  <active>true</active>
  <!-- code (optional identifier) -->
  <code>12345</code>
  <!-- description (optional) -->
  <description>One of our best clients</description>
  <!-- url (optional external link) -->
  <url>http://abc.com</url>
</client>

Response

Status: 201 Created

<client>
  <id type="integer">#{new-client-id}</id>
  <name>ABC Corp</name>
  <active type="boolean">true</active>
  <code>12345</code>
  <description>One of our best clients</description>
  <url>http://abc.com</url>
  <created-at type="datetime">2008-01-07T15:22:33Z</created-at>
  <updated-at type="datetime">2008-01-07T15:22:33Z</updated-at>
</client>

Update

Request

PUT /clients/#{client-id}.xml

Include ANY of the following data with your request:

<client>
  <name>ABC Corp</name>
  <active>true</active>
  <code>12345</code>
  <description>One of our best clients</description>
  <url>http://abc.com</url>
</client>

Response

Status: 200 OK

Delete

Request

DELETE /clients/#{client-id}.xml

Response

Status: 200 OK

Continue to Projects...