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. | [email protected] |
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. | [email protected] |
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>[email protected]</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>[email protected]</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