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:

ParameterDescription
nameCompany name
client_numberClient number
emaile-mail address
first_nameFirst name of the contact person
last_nameLast name of the contact person
country_codeCountry code as ISO 3166 Alpha-2
noteNote
invoice_idID of an invoice of this client, multiple values separated with commas
tagsComma 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 elementDescriptionTypeDefault valueMandatory
archivedState of archival storage. 1=archived, 0=activeBOOL0
number_prePrefixALNUMValue from settings
numbersequential numberINTnext free number
number_lengthMinimum length of the customer number (to be filled with leading zeros)INTValue from settings
nameCompany nameALNUM
streetStreetALNUM
zipZip codeALNUM
cityCityALNUM
stateState, county, district, regionALNUM
country_codeCountryCountry code as ISO 3166 Alpha-2Value from your own company
first_nameFirst nameALNUM
last_nameLast nameALNUM
salutationSalutationALNUM
phonePhoneALNUM
faxFaxALNUM
mobilemobile numberALNUM
emailEmailvalid Email address
wwwWebsiteURL (w/o http)
tax_numberTax numberALNUM
vat_numberVAT numbervalid VAT number
bank_account_numberBank account numberALNUM
bank_account_ownerBank account ownerALNUM
bank_numberBank identifier codeALNUM
bank_nameBank nameALNUM
bank_swiftSWIFT/BICALNUM
bank_ibanIBANvalid IBAN
sepa_mandateMandate reference of a SEPA Direct Debit mandateALNUM
sepa_mandate_dateDate of issue of the SEPA Direct Debit mandateDATE
localeLocale of the client. If no value is passed, the locale of the account will be applied to the client.ALNUM
tax_ruleTax RuleTAX, NO_TAX, COUNTRYCOUNTRY
default_payment_typesPayment 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_grossPrice basis (net, gross, according to account settings)NET, GROSS, SETTINGSSETTINGS
noteNoteALNUM
reductionReduction in percentFLOAT
discount_rate_typeType of the default value for discount rateSETTINGS, ABSOLUTE, RELATIVESETTINGS
discount_rateDiscount rateFLOAT
discount_days_typeType of the default value for discount intervalSETTINGS, ABSOLUTE, RELATIVESETTINGS
discount_daysDiscount period in daysFLOAT
due_days_typeType of the default value for maturitySETTINGS, ABSOLUTE, RELATIVESETTINGS
due_daysMaturity in days from invoice dateINT
reminder_due_days_typeType of the default value for reminder maturitySETTINGS, ABSOLUTE, RELATIVESETTINGS
reminder_due_daysReminder maturityINT
offer_validity_days_typeType of the default value for validity of estimatesSETTINGS, ABSOLUTE, RELATIVESETTINGS
offer_validity_daysValidity of estimatesINT
currency_codeThe currency for this client. If this field is empty, the account currency is used.ISO currency code
price_groupArtciles can have several prices. The pricegroup defines which price applies to the client.INT
debitor_account_numberDebitor account numberINT
dunning_runAutomated 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.