List all clients

GET /api/clients
<?xml version="1.0" encoding="UTF-8"?>
<clients type="array" page="1" per_page="100" total="2">
    <client>
        ...
    </client>
    <client>
        ...
    </client>
</clients>

The list can be filtered with parameters:

GET /api/clients?name=gmbh

Shows all clients with the term “gmbh” in their name. It doesn’t matter if you use upper- or lowercase.
The following parameters can be used:

Parameter Description
name Company name
client_number Client number
email e-mail address
first_name First name of the contact person
last_name Last name of the contact person
country_code Country code as ISO 3166 Alpha-2
note Note
invoice_id ID of an invoice of this client, multiple values separated with commas
tags Comma separated list of tags

Your own account info

GET /api/clients/myself

If you use “myself” as ID, the data of your own account is returned.

Show a specific client

GET /api/clients/{id}
<?xml version="1.0" encoding="UTF-8"?>
<client>
    <id type="integer">1</id>
    <created type="datetime">2007-12-13T12:12:00+01:00</created>
    <archived>0</archived>
    <client_number>KD123</client_number>
    <number type="integer">123</number>
    <number_pre>KD</number_pre>
    <number_length type="integer">0</number_length>
    <name>Musterfirma</name>
    <salutation>Mr</salutation>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
    <street>Teststreet 123</street>
    <zip>12345</zip>
    <city>Foo City</city>
    <state>Test State Island</state>
    <country_code>US</country_code>
    <address>Mr John Doe
Teststreet 123
12345 Foo City</address> <!-- read only -->
    <phone>+49 123456789</phone>
    <fax>+49 123456789</fax>
    <mobile>+49 123456789</mobile>
    <email>info@example.com</email>
    <www>www.example.com</www>
    <tax_number>12/3456/789</tax_number>
    <vat_number>DE123456789</vat_number>
    <bank_account_owner>John Doe</bank_account_owner>
    <bank_number>123456789</bank_number>
    <bank_name>Deutsche Bank</bank_name>
    <bank_account_number>123456789</bank_account_number>
    <bank_swift>SWIFT/BIC</bank_swift>
    <bank_iban>IBAN</bank_iban>
    <enable_customerportal>1</enable_customerportal>
    <customerportal_url>https://mybillomatid.billomat.net/customerportal/auth/autologin/entityId/123?hash=123456789aabbcc</customerportal_url>
    <sepa_mandate>MN123</sepa_mandate>
    <sepa_mandate_date>2013-12-10</sepa_mandate_date>    
    <tax_rule>COUNTRY</tax_rule>
    <net_gross>SETTINGS</net_gross>
    <default_payment_types>CASH,PAPAL</default_payment_types>
    <reduction>10</reduction>
    <discount_rate_type>SETTINGS</discount_rate_type>
    <discount_rate>2</discount_rate>
    <discount_days_type>SETTINGS</discount_days_type>
    <discount_days>7</discount_days>
    <due_days_type>SETTINGS</due_days_type>
    <due_days>14</due_days>
    <reminder_due_days_type>RELATIVE</reminder_due_days_type>
    <reminder_due_days>-2</reminder_due_days>
    <offer_validity_days_type>ABSOLUTE</offer_validity_days_type>
    <offer_validity_days>30</offer_validity_days>
    <currency_code>CHF</currency_code>
    <price_group>2</price_group>
    <debitor_account_number>10000</debitor_account_number>
	<dunning_run>0</dunning_run>
    <note>Really nice custumer</note>
    <revenue_gross type="float">1900</revenue_gross> <!-- read only -->
    <revenue_net type="float">1000</revenue_net> <!-- read only -->
</client>

Create a client

POST /api/clients
XML element Description Type Default value Mandatory
archived State of archival storage. 1=archived, 0=active BOOL 0
number_pre Prefix ALNUM Value from settings
number sequential number INT next free number
number_length Minimum length of the customer number (to be filled with leading zeros) INT Value from settings
name Company name ALNUM
street Street ALNUM
zip Zip code ALNUM
city City ALNUM
state State, county, district, region ALNUM
country_code Country Country code as ISO 3166 Alpha-2 Value from your own company
first_name First name ALNUM
last_name Last name ALNUM
salutation Salutation ALNUM
phone Phone ALNUM
fax Fax ALNUM
mobile mobile number ALNUM
email Email valid Email address
www Website URL (w/o http)
tax_number Tax number ALNUM
vat_number VAT number valid VAT number
bank_account_number Bank account number ALNUM
bank_account_owner Bank account owner ALNUM
bank_number Bank identifier code ALNUM
bank_name Bank name ALNUM
bank_swift SWIFT/BIC ALNUM
bank_iban IBAN valid IBAN
sepa_mandate Mandate reference of a SEPA Direct Debit mandate ALNUM
sepa_mandate_date Date of issue of the SEPA Direct Debit mandate DATE
locale Locale of the client. If no value is passed, the locale of the account will be applied to the client. ALNUM
tax_rule Tax Rule TAX, NO_TAX, COUNTRY COUNTRY
default_payment_types Payment Type (eg. CASH, BANK_TRANSFER, PAYPAL, …). More than one payment type could be given as a comma separated list. Theses payment types will be logically OR-connected. You can find a overview of all payment types at API documentation of payments. If no value is passed, the customer will be offered the payment types specified at the account settings. ALNUM
net_gross Price basis (net, gross, according to account settings) NET, GROSS, SETTINGS SETTINGS
note Note ALNUM
reduction Reduction in percent FLOAT
discount_rate_type Type of the default value for discount rate SETTINGS, ABSOLUTE, RELATIVE SETTINGS
discount_rate Discount rate FLOAT
discount_days_type Type of the default value for discount interval SETTINGS, ABSOLUTE, RELATIVE SETTINGS
discount_days Discount period in days FLOAT
due_days_type Type of the default value for maturity SETTINGS, ABSOLUTE, RELATIVE SETTINGS
due_days Maturity in days from invoice date INT
reminder_due_days_type Type of the default value for reminder maturity SETTINGS, ABSOLUTE, RELATIVE SETTINGS
reminder_due_days Reminder maturity INT
offer_validity_days_type Type of the default value for validity of estimates SETTINGS, ABSOLUTE, RELATIVE SETTINGS
offer_validity_days Validity of estimates INT
currency_code The currency for this client. If this field is empty, the account currency is used. ISO currency code
price_group Artciles can have several prices. The pricegroup defines which price applies to the client. INT
debitor_account_number Debitor account number INT
dunning_run Automated dunning run? BOOL
<client>
    <name>Musterfirma</name>
    <salutation>Herr</salutation>
    <first_name>Max</first_name>
    <last_name>Muster</last_name>
    <street>Musterstraße 123</street>
    <zip>12345</zip>
    <city>Musterstadt</city>
    <state>Bundesland</state>
    <country_code>DE</country_code>
    <phone>+49 123456789</phone>
    <fax>+49 123456789</fax>
    <email>info@example.com</email>
    <www>www.example.com</www>
    <tax_number>12/3456/789</tax_number>
    <vat_number>DE123456789</vat_number>
    <bank_account_owner>Kontoinhaber</bank_account_owner>
    <bank_number>123456789</bank_number>
    <bank_name>Deutsche Bank</bank_name>
    <bank_account_number>123456789</bank_account_number>
    <bank_swift>SWIFT/BIC</bank_swift>
    <bank_iban>IBAN</bank_iban>
</client>
<?xml version="1.0" encoding="UTF-8"?>
<client>
    ...
</client>

Edit client

PUT /api/clients/{id}
<client>
    <name>ACME</name>
</client>
<?xml version="1.0" encoding="UTF-8"?>
<client>
    ...
</client>

Delete client

DELETE /api/clients/{id}

This is only possible if no documents exist for this client.

Response: 200 OK

Show a client image (avatar)

GET /api/clients/{id}/avatar?size={size}

Returns the avatar for the client with the given ID. The image is cut square. The size in pixels can be specified by the size paramater.