Staff access

Staff have access to the API calls listed below if the Clients tab is enabled for staff. Each staff member can only view and edit clients that he or she is assigned to.

client.create

Create a new client and return the corresponding client_id. If a password is not supplied, one will be created at random.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="client.create">
  <client>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <organization>ABC Corp</organization>
    <email>janedoe@freshbooks.com</email>
    <username>janedoe</username>            # Defaults to e-mail address (Optional)
    <password>seCret!7</password>           # Defaults to random password (Optional)
    <work_phone>(555) 123-4567</work_phone> # (Optional)
    <home_phone>(555) 234-5678</home_phone> # (Optional)
    <mobile></mobile>                       # (Optional)
    <fax></fax>                             # (Optional)
    <notes></notes>                         # (Optional)

    <p_street1>123 Fake St.</p_street1>     # Primary address (All optional)
    <p_street2>Unit 555</p_street2>
    <p_city>New York</p_city>
    <p_state>New York</p_state>
    <p_country>United States</p_country>
    <p_code>553132</p_code>

    <s_street1></s_street1>                 # Secondary address (All optional)
    <s_street2></s_street2>
    <s_city></s_city>
    <s_state></s_state>
    <s_country></s_country>
    <s_code></s_code>
  </client>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <client_id>13</client_id>
</response>

client.update

Update the details of the client with the given client_id. Any fields not referenced in the request will remain unchanged.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="client.update">
  <client>
    <client_id>13</client_id>

    # Same params as client.create
  </client>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

client.get

Return the client details associated with the given client_id.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="client.get">
  <client_id>13</client_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <client>
    <client_id>13</client_id>

    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <organization>ABC Corp</organization>
    <email>janedoe@freshbooks.com</email>
    <username>janedoe</username>
    <work_phone>(555) 123-4567</work_phone>
    <home_phone>(555) 234-5678</home_phone>
    <mobile></mobile>
    <fax></fax>
    <credit>123.45</credit>
    <notes></notes>                         

    <p_street1>123 Fake St.</p_street1>
    <p_street2>Unit 555</p_street2>
    <p_city>New York</p_city>
    <p_state>New York</p_state>
    <p_country>United States</p_country>
    <p_code>553132</p_code>

    <s_street1></s_street1>
    <s_street2></s_street2>
    <s_city></s_city>
    <s_state></s_state>
    <s_country></s_country>
    <s_code></s_code>
  </client>
</response>

client.delete

Delete the client with the given client_id.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="client.delete">
  <client_id>13</client_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

client.list

Returns a list of client summaries in order of descending client_id.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="client.list">
  <email>janedoe@freshbooks.com</email> # Filter by email address (Optional)
  <username>janedoe</username>          # Filter by username (Optional)
  <page>1</page>                        # The page number to show (Optional)
  <per_page>15</per_page>               # Number of results per page, default 25 (Optional)
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <clients page="1" per_page="15" pages="3" total="42">
    <client>
      <client_id>13</client_id>
      <organization>ABC Corp</organization>
      <username>janedoe</username>
      <first_name>Jane</first_name>
      <last_name>Doe</last_name>
      <email>janedoe@freshbooks.com</email>
    </client>
    ...
  </clients>
</response>