Items from the domain “clients” represent a customer.


Structure of URLs:

https://api.simplybooks.be/api/v1/clients: Customer details

https://api.simplybooks.be/api/v1/clients/1001: Customer with ID 1001

https://api.simplybooks.be/api/v1/clients/1001/contacts: Customer contact information with ID 1001

https://api.simplybooks.be/api/v1/clients/1001/details: Details of customer with ID 1001


Domain: clients

Field nameTypeDefinition
Example
client_idintUnique ID of the customer. Generated by the system. Always mandatory to enter in URL (except when creating).
1001
uritextURL to customer. Generated by the system. To be used when addressing the customer via the API. 
external_client_idtext(Unique) Customer ID that can be set by a third party. Maximum 50 characters long. Uniqueness of value is not enforced. Client-98437
nametextName of the customer. Mandatory to give at creation. Maximum 75 characters long. IT Services BVBA
attentiontextAttn. (regarding to) the customer. Not required. Maximum 75 karakters long.admin department
numbertextCustomer number. Not mandatory, maximum 55 characters long. Generated automatically if not specified at creation and when this option is activated in the Settings.B12548
streettextStreet + house number of the customer. Not mandatory, maximum 150 characters long.Langestraat 189
street2textSecond address line of the customer. Not mandatory, maximum 150 characters long.
citytextCity of the customer. Not mandatory, maximum 50 characters long.
Antwerp
postal_codetextZip code of the customer's city. Not mandatory, maximum 10 characters long.2000
countrytextCustomer's country. Not mandatory, maximum 25 characters long. Can only be used when creating/editing if country_code was not specified. When requested, this field is automatically determined by means of country_code.Belgium
country_codetextCustomer country code. Not required, 2 characters long, in capital letters.BE
delivery_addressAddressShipping address of the customer. Not required.
site_addressAddressCustomer's site address. Not required.
tax_codetextVAT number of the customer. Not mandatory, maximum 75 characters long.BE 0123.456.789
tax_code_registration_pendingtextIndication of the VAT number of the customer is in request. Can have a value of 'yes' or 'no'. If not specified or if tax_code entered, the default value is 'no'.
no
company_idtextCompany number of the customer. Not mandatory, maximum 75 characters long.0123.456.789
email_addresstextEmail address of the customer. Not mandatory, maximum 125 characters long.info@hisdomain.com
phone_numbertextCustomer phone number. Not mandatory, maximum 20 characters long.
098/90.20.00
websitetextThe URL of the customer's website. Not mandatory, maximum 150 characters long.
http://www.it-servicesbvba.be
statetextThe status of customer. Possible values: 'active', 'archived'. Defaults to 'active'.
active
private_notetextField with private comments about the customer. Can be used freely. Not required.Always pays correctly.
private_note_htmlhtmlField with private comments about the customer in HTML format. Can be used freely. Not required.
<p>Always pays correctly</p>
last_activitydatetimeTime with the last activity of the customer. Cannot be specified, is automatically determined by the system.2018-05-03 11:33:45
default_days_invoice_dueintStandard number of days payment term new invoices. Not required. If not specified, the default is used as set in the settings of the account.30
default_days_quote_validintStandard number of days validity period new quotations. Not required. If not specified, the default is used as set in the settings of the account.30
default_tax_categoryintStandard VAT rate. Can contain the value 0, 1, 2 or 3 where 1 (VAT rate 1) is the default value. Not required.
0
default_tax_category_special_statustextThe VAT code for VAT exemption. Can only be set in combination with default_tax_category 0. Up to 20 characters long. Not required. A list of available codes as used in the software can be retrieved by setting the default VAT rate via the web interface.
MC
default_discount_percentagefloatStandard discount percentage for new invoices from the customer. Amount must be between 0 and 100. Numbers up to 2 digits after the comma are allowed. Not required. If not specified, the default is used as set in the settings of the account.
5
default_cash_discount_activetextIndication whether or not the financial discount for the customer is activated by default when creating new invoices. Can have a value of 'yes' or 'no'. Not required. If not specified, the default is used as set in the settings of the account.
no
default_cash_discount_percentagefloatStandard discount percentage financial discount for new invoices from the customer. Amount must be between 0 and 100. Numbers up to 2 digits after the comma are allowed. Not required. If not specified, the default is used as set in the settings of the account.    
1.50
default_cash_discount_days_validintStandard number of days validity financial discount for new invoices from the customer. Amount must be between 0 and 100. Only integers are allowed. Not required. If not specified, the default is used as set in the settings of the account.8
default_structured_messagetextSend out automatic reminders for new invoices from this customer by default. Can have a value of 'yes' or 'no'. Not required. If not specified, the default is used as set in the settings of the account.342485986564
default_automatic_reminderstextSend out automatic reminders for new invoices from this customer by default. Can have a value of 'yes' or 'no'. Not required. If not specified, the default is used as set in the settings of the account.
yes
default_languagetextStandard language new invoices. Possible values: 'dutch', 'french', 'english', 'german'. Not required. If not specified, the default language 'dutch' is used.french
default_currencytextStandard currency new invoices. Contains the official code of the currency (e.g. 'EUR', 'USD' or 'GBP'). If not specified, the default currency 'EUR' will be used.USD
default_notetextNote that is added when creating an invoice, quotation or other document. Can be used in combination with default_note_position.Customer description
default_note_htmlhtmlNote that is added when creating an invoice, quotation or other document. Can be used in combination with default_note_position.
<p>Customer description</p>
default_note_positiontextThe position of the note in relation to pre-existing standard note. Can contain the value 'top', 'bottom' or 'replace'. Can be used in combination with default_note.
replace
default_invoices_layout_idintStandard layout for new invoices. Empty by default. If empty, the account's default invoice layout is used.
8001
default_receipts_layout_idintStandard layout for new receipts. Empty by default. If empty, the default receipt layout of the account is used.8001
default_quotes_layout_idintStandard layout for new quotations. Empty by default. If empty, the default layout for quotations of the account is used.8001
default_orders_layout_idintStandard layout for new order forms. Empty by default. If empty, the default order form layout of the account is used.8001
default_deliveries_layout_idintStandard layout for new delivery notes. Empty by default. If empty, the account's default delivery note layout is used.8001
sepa_collectionSepaData to activate SEPA direct debit for the customer.
invoice_countintNumber of invoices registered under the customer. Determined by the system itself.12
receipt_countintNumber of receipts registered under the customer. Determined by the system itself.2
quote_countintNumber of quotations registered under the customer. Determined by the system itself.0
order_countintNumber of order forms registered under the customer. Determined by the system itself.0
delivery_countintNumber of delivery notes registered under the customer. Determined by the system itself.3
subscription_countintNumber of subscriptions registered under the customer. Determined by the system itself.1
contactslistA list of contacts within the company/customer.
detailslistDEPRECATED. A generic list of data within the company/customer. This information is no longer available for new accounts. Alternatively, you can use "custom_values".
custom_valueslistList of default fields. The available fields are added via "Settings" > "Advanced".


Subdomain: contacts ( < clients )

Field name
TypeDefinition
Example
contact_idintUnique ID of the contact person. Generated by the system. Mandatory to enter in URL (except for creation).2002
client_idintUnique ID of the customer. Generated by the system. Required to enter in URL.1001
urltextURL to contact person. Generated by the system. To be used when addressing contact person via the API.
contact_nametextName or description of the contact person. Mandatory to give at creation. Maximum 254 characters long.John Smith
email_addresstextEmail address of the contact person. Not mandatory if phone_number given. Maximum 125 characters long.john.smith@hisdomain.com
phone_numbertextPhone number of the contact person. Not mandatory if email_address given. Maximum 20 characters long.098/90.20.20


Subdomain : details ( < clients )

Deprecated! This information is no longer available for new accounts. Alternatively, you can use "custom_values".

Field name
TypeDefinition
Example
detail_idintUnique ID of the detail data. Generated by the system. Mandatory to enter in URL (except for creation).    2012
client_idintUnique ID of the customer. Generated by the system. Required to enter in URL.1001
urltextURL to detail data. Generated by the system. To be used when addressing details along the API.
nametextName or description of the detail data. Mandatory to give at creation. Maximum 75 characters long.Bank
valuetextValue of the detail data. Mandatory to give at creation. Maximum 100 characters long.000-00000011-11


Subdomain : custom_values ( < clients )

Field name
TypeDefinition
Example
nametextInternal name of the default field. Determined when the default field is created and can be used as a unique identifier of the default field. Mandatory when adding or changing the value of this field.myreference
descriptiontextName or description of the default field as it appears when used. Is only returned informatively and cannot be modified via the API.our reference
valuetextValue of the default field. Maximum 75 characters long.
123456


Type : Address

Field name
TypeDefinition
Example
streettextStreet + house number of the address. Not mandatory, maximum 150 characters long.Langestraat 189
street2textSecond address line of the address. Not mandatory, maximum 150 characters long.
citytextCity of address. Not mandatory, maximum 50 characters long.Antwerp
postal_codetextThe postal code of the city of the address. Not mandatory, maximum 10 characters long.2000
countrytextCustomer's country. Could not be specified. Is automatically determined by means of country_code.Belgium
country_codetextCustomer country code. Mandatory, 2 characters long, in capital letters.
BE


Type : Sepa

Field name
TypeDefinition
Example
nametextCustomer name as known for the account number. Not mandatory, maximum 100 characters long.
John Smith
ibantextIBAN of the customer's account number. Not mandatory, maximum 50 characters long. BE938493849384349
bictextBIC of the customer's account number. Not mandator, maximum 50 characters long.BEXXXXXXXX
mandate_datetextDate of signature of mandate. Not required, format YYYY-MM-DD.2021-01-01
mandate_referencetextReference to the mandate. Not mandatory, maximum 100 characters long.SEPA-REF-1


Example in XML of a customer:

<client>
    <client_id>1001</client_id>
    <uri>https://eenvoudigfactureren.be/api/v1/clients/1001</uri>
    <external_client_id>Client-98437</external_client_id>
    <number>B12548</number>
    <name>IT Services BVBA</name>
    <attention>dienst administratie</attention>
    <street>Langestraat 189</street>
    <street2></street2>
    <city>Antwerpen</city>
    <postal_code>2000</postal_code>
    <country>België</country>
    <country_code>BE</country_code>
    <delivery_address>
        <street>Gebouw X</street>
        <street2>Kortestraat 3</street2>
        <postal_code>2000</postal_code>
        <city>Antwerpen</city>
        <country>België</country>
        <country_code>BE</country_code>
    </delivery_address>
    <site_address>
        <street>Olifantstraat 200</street>
        <street2></street2>
        <postal_code>9000</postal_code>
        <city>Gent</city>
        <country>België</country>
        <country_code>BE</country_code>
    </site_address>
    <tax_code>BE 0123.456.789</tax_code>
    <company_id></company_id>
    <email_address>info@hisdomain.com</email_address>
    <phone_number>098/90.20.00</phone_number>
    <website>http://www.it-servicesbvba.be</website>
    <state>active</state>
    <private_note>Betaald steeds correct.</private_note>
    <private_note_html><![CDATA[<p>Betaald steeds correct.</p>]]></private_note_html>
    <last_activity>2018-05-03 11:33:45</last_activity>
    <default_days_invoice_due>30</default_days_invoice_due>
    <default_days_quote_valid>30</default_days_quote_valid>
    <default_tax_category>0</default_tax_category>
    <default_tax_category_special_status>MC</default_tax_category_special_status>
    <default_structured_message>342485986564</default_structured_message>
    <default_automatic_reminders>yes</default_automatic_reminders>
    <default_language>french</default_language>
    <default_currency>USD</default_currency>
    <default_note>Omschrijving klant</default_note>
    <default_note_html><![CDATA[<p>Omschrijving klant</p>]]></default_note_html>
    <default_note_position>replace</default_note_position>
    <default_invoices_layout_id>8001</default_invoices_layout_id>
    <default_receipts_layout_id>8001</default_receipts_layout_id>
    <default_quotes_layout_id>8001</default_quotes_layout_id>
    <default_orders_layout_id>8001</default_orders_layout_id>
    <default_deliveries_layout_id>8001</default_deliveries_layout_id>
    <sepa_collection>
        <name>John Smith</name>
        <iban>BE938493849384349</iban>
        <bic>BEXXXXXXXX</bic>
        <mandate_date>2021-01-01</mandate_date>
        <mandate_reference>SEPA-REF-1</mandate_reference>
    </sepa_collection>
    <invoice_count>12</invoice_count>
    <receipt_count>7</receipt_count>
    <quote_count>7</quote_count>
    <order_count>0</order_count>
    <delivery_count>0</delivery_count>
    <subscription_count>1</subscription_count>
    <contacts>
        <contact>
            <contact_id>2002</contact_id>
            <uri>https://eenvoudigfactureren.be/api/v1/clients/1001/contacts/2002</uri>
            <contact_name>John Smith</contact_name>
            <email_address>john.smith@hisdomain.com</email_address>
            <phone_number>098/90.20.20</phone_number>
        </contact>
    </contacts>
    <details>
        <detail>
            <contact_id>2012</contact_id>
            <uri>https://eenvoudigfactureren.be/api/v1/clients/1001/details/2012</uri>
            <name>Bankrekeningnummer</name>
            <value>000-00000011-11</value>
        </detail>
    </details>
    <custom_values>
        <custom_value>
            <name>myreference</name>
            <description>Onze referentie</description>
            <value>123456</value>
        </custom_value>
    </custom_values>
</client>


  More info about the API? Read the useful articles below