Clients

Staff have access to the API calls listed below if the Clients tab is enabled for staff. Each staff member can create clients, and view and edit clients that they are 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>
    <!-- Defaults to first name + last name (Optional) -->
    <username>janedoe</username>
    <!-- Defaults to random password (Optional) -->
    <password>seCret!7</password>
	<!-- (Optional) -->
	<contacts>
		<contact>
	       <username>alex</username>
	       <first_name></first_name>
	       <last_name></last_name>
			<!-- (Email address is the only required field) -->
	       <email>test@freshbooks.com</email>
	       <phone1></phone1>
	       <phone2></phone2>
		</contact>
	</contacts>
	<!-- (Optional) -->
    <work_phone>(555) 123-4567</work_phone>
    <!-- (Optional) -->
    <home_phone>(555) 234-5678</home_phone>
    <!-- (Optional) -->
    <mobile></mobile>
    <!-- (Optional) -->
    <fax></fax>
    <!-- See language.list for codes. (Optional) -->
    <language>en</language>
    <!-- (Optional) -->
    <currency_code>USD</currency_code>
    <!-- (Optional) -->
    <notes></notes>

    <!-- Primary address (All optional) -->
    <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>

    <!-- Secondary address (All optional) -->
    <s_street1></s_street1>
    <s_street2></s_street2>
    <s_city></s_city>
    <s_state></s_state>
    <s_country></s_country>
    <s_code></s_code>
    <!-- e.g. 'VAT Number' (Optional) -->
    <vat_name></vat_name>
    <!-- If set, shown with vat_name under client address (Optional) -->
    <vat_number></vat_number>
  </client>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" 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 xmlns="http://www.freshbooks.com/api/" status="ok"/>

client.get

Return the client details associated with the given client_id.

  • The credit element is deprecated and will only represent credit in the system’s base currency. A new element, called credits has been added with child elements for each currency that the client has credit in.

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 xmlns="http://www.freshbooks.com/api/" 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>
	    <contacts>
	       <contact_id>15</contact_id>
	       <username>alex</username>
	       <first_name></first_name>
	       <last_name></last_name>
	       <email>johnmcnicol@freshbooks.com</email>
	       <phone1></phone1>
	       <phone2></phone2>
	   </contacts>
	<work_phone>(555) 123-4567</work_phone>
    <home_phone>(555) 234-5678</home_phone>
    <mobile></mobile>
    <fax></fax>
    <language>en</language>
    <currency_code>USD</currency_code>

    <credit currency="USD" deprecated="true">123.45</credit>
    <credits>
        <credit currency="USD">123.45</credit>
        <credit currency="CAD">43.45</credit>
        <credit currency="EUR">12.00</credit>
    </credits>
    <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>
    <url deprecated="true">https://sample.freshbooks.com/view/Vbbfs324trTkxer</url>
    <auth_url deprecated="true">https://sample.freshbooks.com/clients/13</auth_url>
    <links>
      <client_view>https://sample.freshbooks.com/view/Vbbfs324trTkxer</client_view>
      <view>https://sample.freshbooks.com/clients/13</view>
      <statement>https://sample.freshbooks.com/view/3EbEwAkJGJkuJHSN</statement>
    </links>
    <vat_name></vat_name>
    <vat_number></vat_number>
    <folder>active</folder>
    <!-- (Read-only) -->
    <updated>2009-08-12 09:00:00</updated>
  </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 xmlns="http://www.freshbooks.com/api/" status="ok"/>

client.list

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

Note: This method uses pagination.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="client.list">
  <!-- Filter by email address (Optional) -->
  <email>janedoe@freshbooks.com</email>
  <!-- Filter by username (Optional) -->
  <username>janedoe</username>
  <!-- Return only clients modified since this date (Optional) -->
  <updated_from>2009-01-01 00:00:00</updated_from>
  <!-- Return only clients modified before this date (Optional) -->
  <updated_to>2009-12-01 00:00:00</updated_to>
  <!-- The page number to show (Optional) -->
  <page>1</page>
  <!-- Number of results per page, default 25 (Optional) -->
  <per_page>15</per_page>
  <!-- One of 'active', 'archived', 'deleted' -->
  <folder>active</folder>
  <!-- Return only clients with this text in their 'notes' (Optional) -->
  <notes>email</notes>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <clients page="1" per_page="15" pages="3" total="42">
    <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>
	    <contacts>
	       <contact_id>15</contact_id>
	       <username>alex</username>
	       <first_name></first_name>
	       <last_name></last_name>
	       <email>johnmcnicol@freshbooks.com</email>
	       <phone1></phone1>
	       <phone2></phone2>
	   </contacts>
	  <work_phone>(555) 123-4567</work_phone>
      <home_phone>(555) 234-5678</home_phone>
      <mobile></mobile>
      <fax></fax>
      <language>en</language>
      <currency_code>USD</currency_code>
      <credit currency="USD" deprecated="true">123.45</credit>
      <credits>
          <credit currency="USD">123.45</credit>
          <credit currency="CAD">43.45</credit>
          <credit currency="EUR">12.00</credit>
      </credits>
      <notes>Prefers email over phone calls</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>
      <url deprecated="true">https://sample.freshbooks.com/view/Vbbfs324trTkxer</url>
      <auth_url deprecated="true">https://sample.freshbooks.com/clients/13</auth_url>
      <links>
        <client_view>https://sample.freshbooks.com/view/Vbbfs324trTkxer</client_view>
        <view>https://sample.freshbooks.com/clients/13</view>
        <statement>https://sample.freshbooks.com/view/3EbEwAkJGJkuJHSN</statement>
      </links>
      <vat_name></vat_name>
      <vat_number></vat_number>
      <updated>2009-08-12 09:00:00</updated>
      <folder>active</folder>
    </client>
    ...
  </clients>
</response>

Search