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 name | Type | Definition | Example |
|---|---|---|---|
| client_id | int | Unique ID of the customer. Generated by the system. Always mandatory to enter in URL (except when creating). | 1001 |
| uri | text | URL to customer. Generated by the system. To be used when addressing the customer via the API. | – |
| external_client_id | text | (Unique) Customer ID that can be set by a third party. Maximum 50 characters long. Uniqueness of value is not enforced. | Client-98437 |
| name | text | Name of the customer. Mandatory to give at creation. Maximum 75 characters long. | IT Services BVBA |
| attention | text | Attn. (regarding to) the customer. Not required. Maximum 75 karakters long. | admin department |
| number | text | Customer number. Not mandatory, maximum 55 characters long. Generated automatically if not specified at creation and when this option is activated in the Settings. | B12548 |
| street | text | Street + house number of the customer. Not mandatory, maximum 150 characters long. | Langestraat 189 |
| street2 | text | Second address line of the customer. Not mandatory, maximum 150 characters long. | |
| city | text | City of the customer. Not mandatory, maximum 50 characters long. | Antwerp |
| postal_code | text | Zip code of the customer's city. Not mandatory, maximum 10 characters long. | 2000 |
| country | text | Customer'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_code | text | Customer country code. Not required, 2 characters long, in capital letters. | BE |
| delivery_address | Address | Shipping address of the customer. Not required. | – |
| site_address | Address | Customer's site address. Not required. | – |
| tax_code | text | VAT number of the customer. Not mandatory, maximum 75 characters long. | BE 0123.456.789 |
| tax_code_registration_pending | text | Indication 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_id | text | Company number of the customer. Not mandatory, maximum 75 characters long. | 0123.456.789 |
| email_address | text | Email address of the customer. Not mandatory, maximum 125 characters long. | info@hisdomain.com |
| phone_number | text | Customer phone number. Not mandatory, maximum 20 characters long. | 098/90.20.00 |
| website | text | The URL of the customer's website. Not mandatory, maximum 150 characters long. | http://www.it-servicesbvba.be |
| state | text | The status of customer. Possible values: 'active', 'archived'. Defaults to 'active'. | active |
| private_note | text | Field with private comments about the customer. Can be used freely. Not required. | Always pays correctly. |
| private_note_html | html | Field with private comments about the customer in HTML format. Can be used freely. Not required. | <p>Always pays correctly</p> |
| last_activity | datetime | Time 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_due | int | Standard 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_valid | int | Standard 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_category | int | Standard 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_status | text | The 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_percentage | float | Standard 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_active | text | Indication 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_percentage | float | Standard 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_valid | int | Standard 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_message | text | Send 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_reminders | text | Send 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_language | text | Standard language new invoices. Possible values: 'dutch', 'french', 'english', 'german'. Not required. If not specified, the default language 'dutch' is used. | french |
| default_currency | text | Standard 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_note | text | Note that is added when creating an invoice, quotation or other document. Can be used in combination with default_note_position. | Customer description |
| default_note_html | html | Note 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_position | text | The 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_id | int | Standard layout for new invoices. Empty by default. If empty, the account's default invoice layout is used. | 8001 |
| default_receipts_layout_id | int | Standard layout for new receipts. Empty by default. If empty, the default receipt layout of the account is used. | 8001 |
| default_quotes_layout_id | int | Standard layout for new quotations. Empty by default. If empty, the default layout for quotations of the account is used. | 8001 |
| default_orders_layout_id | int | Standard layout for new order forms. Empty by default. If empty, the default order form layout of the account is used. | 8001 |
| default_deliveries_layout_id | int | Standard layout for new delivery notes. Empty by default. If empty, the account's default delivery note layout is used. | 8001 |
| sepa_collection | Sepa | Data to activate SEPA direct debit for the customer. | – |
| invoice_count | int | Number of invoices registered under the customer. Determined by the system itself. | 12 |
| receipt_count | int | Number of receipts registered under the customer. Determined by the system itself. | 2 |
| quote_count | int | Number of quotations registered under the customer. Determined by the system itself. | 0 |
| order_count | int | Number of order forms registered under the customer. Determined by the system itself. | 0 |
| delivery_count | int | Number of delivery notes registered under the customer. Determined by the system itself. | 3 |
| subscription_count | int | Number of subscriptions registered under the customer. Determined by the system itself. | 1 |
| contacts | list | A list of contacts within the company/customer. | – |
| details | list | DEPRECATED. 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_values | list | List of default fields. The available fields are added via "Settings" > "Advanced". | – |
Subdomain: contacts ( < clients )
| Field name | Type | Definition | Example |
|---|---|---|---|
| contact_id | int | Unique ID of the contact person. Generated by the system. Mandatory to enter in URL (except for creation). | 2002 |
| client_id | int | Unique ID of the customer. Generated by the system. Required to enter in URL. | 1001 |
| url | text | URL to contact person. Generated by the system. To be used when addressing contact person via the API. | – |
| contact_name | text | Name or description of the contact person. Mandatory to give at creation. Maximum 254 characters long. | John Smith |
| email_address | text | Email address of the contact person. Not mandatory if phone_number given. Maximum 125 characters long. | john.smith@hisdomain.com |
| phone_number | text | Phone 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 | Type | Definition | Example |
|---|---|---|---|
| detail_id | int | Unique ID of the detail data. Generated by the system. Mandatory to enter in URL (except for creation). | 2012 |
| client_id | int | Unique ID of the customer. Generated by the system. Required to enter in URL. | 1001 |
| url | text | URL to detail data. Generated by the system. To be used when addressing details along the API. | – |
| name | text | Name or description of the detail data. Mandatory to give at creation. Maximum 75 characters long. | Bank |
| value | text | Value of the detail data. Mandatory to give at creation. Maximum 100 characters long. | 000-00000011-11 |
Subdomain : custom_values ( < clients )
| Field name | Type | Definition | Example |
|---|---|---|---|
| name | text | Internal 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 |
| description | text | Name or description of the default field as it appears when used. Is only returned informatively and cannot be modified via the API. | our reference |
| value | text | Value of the default field. Maximum 75 characters long. | 123456 |
Type : Address
| Field name | Type | Definition | Example |
|---|---|---|---|
| street | text | Street + house number of the address. Not mandatory, maximum 150 characters long. | Langestraat 189 |
| street2 | text | Second address line of the address. Not mandatory, maximum 150 characters long. | |
| city | text | City of address. Not mandatory, maximum 50 characters long. | Antwerp |
| postal_code | text | The postal code of the city of the address. Not mandatory, maximum 10 characters long. | 2000 |
| country | text | Customer's country. Could not be specified. Is automatically determined by means of country_code. | Belgium |
| country_code | text | Customer country code. Mandatory, 2 characters long, in capital letters. | BE |
Type : Sepa
| Field name | Type | Definition | Example |
|---|---|---|---|
| name | text | Customer name as known for the account number. Not mandatory, maximum 100 characters long. | John Smith |
| iban | text | IBAN of the customer's account number. Not mandatory, maximum 50 characters long. | BE938493849384349 |
| bic | text | BIC of the customer's account number. Not mandator, maximum 50 characters long. | BEXXXXXXXX |
| mandate_date | text | Date of signature of mandate. Not required, format YYYY-MM-DD. | 2021-01-01 |
| mandate_reference | text | Reference 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