Clients API

To manage your clients, you can use the following commands.

Description Method URL
Get all contacts GET /api/v1/clients
Get one contact GET /api/v1/clients/{id}
Create new contact POST /api/v1/clients/
Update a contact PUT /api/v1/clients/{id}
Delete a contact DELETE /api/v1/clients/{id}

All attributes used for clients

These are the attributes available in the call to the Clients API.

Attribute Type Note
clientnr integer The client number
contact string(50) Contact name
showcontact boolean Show the contact name on the invoice
company string(50)
address string(50)
address_addon string(50) Extra address line
zipcode string(7)
city string(50)
country integer or string Country id. You can get a list of country id's with the function api/v1/countrylist. When creating or updating a client, you can supply a country id or a country name. We'll then try to find the id of the country you supplied.
phone string(13)
mobile string(13)
email string(255) Invoice is sent to this e-mail address, if the sendmethod is e-mail
addon string(255) Extra information about the client, e.g., a department
bankcode string(32) The IBAN number of the client
biccode string(32)
taxnumber string(18)
tax_shifted boolean If the taxes on the invoice is shifted to the receiver
lastinvoiceread only date When last invoice to this client was sent
sendmethod string(11) How to send the invoice to the receiver.

'mail': print the invoices yourself, we only process it
'email': send invoices through e-mail
'printcenter': send invoice through the printcenter.
paymentmethod string(10) How the invoice is going to be paid.

'bank': normal bank account transfer
'autocollect': the invoice will be collected (incasso)
top integer The term of payment in days. Defines when the invoice has to be paid by the recipient
stddiscount integer Standard discount percentage for this client. Every invoice defined for this client will automatically get this discount percentage.
mailintro string(128) The first line used in the e-mail to address the recipient. Example: "Dear sir/madam,"
reference object Three lines that will be printed on the invoice. Can be used for references to other documents or something else.

In the object are three fields: 'line1', 'line2' and 'line3'. All fieldstypes are strings.
notes string Notes saved for this client
notes_on_invoice boolean Print the field 'notes' on every invoice for the client
active boolean Non-active clients are hidden in the web application.
default_doclang string(2) In what language the invoice will be generated for this client.

empty: default language
'nl': dutch
'en': english
'de': german
'fr': france
'es': spanish
'it': italian
default_category integer The ID of the category. Use the categories api to retrieve a list of categories.
default_emailread only integer ID of used e-mail text
email_reminder string(255) An invoice reminder is sent to this e-mail address
currency string(3) Used currency in invoice. Like 'EUR', 'USD', etc.
mandate_id string The mandate identification
mandate_date date The date of the signature
collecttype string(4) The collection type:
'OOFF ': single direct debit
'FRST': direct debit: first collection
'RCUR': direct debit: recurring collection
tax_type string(5) Will show if the products on the invoice for this client
will be handled as excluding or including tax:
'intax ': products will be handled as including tax
'extax': products will be handled as excluding tax

Create new contact

POST /api/v1/clients/

Create a POST with at least the required attributes.

// setup the API call with the URL and the method
$request = new fsnl_api('https://www.factuursturen.nl/api/v1/clients/', 'POST');

// build the post body we are going to submit
$request->buildPostBody(array(
  'contact' => 'John Doe',
  'showcontact' => true,
  'company' => 'Johnny Bravo Inc.',
  'address' => 'Sir John Road 100',
  'zipcode' => '1337 JB',
  'city' => 'Johnsville',
  'country' => 146,
  'phone' => '010 123 4567',
  'mobile' => '0612 34 56 78',
  'email' => 'johnny@bravo.com',
  'bankcode' => 'NL91INGB0001234567',
  'biccode' => 'INGBNL2A',
  'taxnumber' => 'NL001234567B01',
  'tax_shifted' => false,
  'sendmethod' => 'email',
  'paymentmethod' => 'bank',
  'top' => 3,
  'stddiscount' => 5.30,
  'mailintro' => 'Dear Johnny,',
  'reference' => array(
    'line1' => 'Your ref: ABC123',
    'line2' => 'Our ref: XZX0029/2932/001',
    'line3' => 'Thank you for your order'
  ),
  'notes' => 'This client is always late with his payments',
  'notes_on_invoice' => false,
  'active' => true,
  'default_doclang' => 'en',
  'email_reminder' => 'reminder@bravo.com',
  'currency' => 'USD',
  'tax_type' => 'intax'
));

Or as a JSON:

{
  "contact": "John Doe",
  "showcontact": true,
  "company": "Johnny Bravo Inc.",
  "address": "Sir John Road 100",
  "zipcode": "1337 JB",
  "city": "Johnsville",
  "country": 146,
  "phone": "010 123 4567",
  "mobile": "0612 34 56 78",
  "email": "johnny@bravo.com",
  "bankcode": "NL91INGB0001234567",
  "biccode": "INGBNL2A",
  "taxnumber": "NL001234567B01",
  "tax_shifted": false,
  "sendmethod": "email",
  "paymentmethod": "bank",
  "top": 3,
  "stddiscount": 5.3,
  "mailintro": "Dear Johnny,",
  "reference": {
    "line1": "Your ref: ABC123",
    "line2": "Our ref: XZX0029/2932/001",
    "line3": "Thank you for your order"
  },
  "notes": "This client is always late with his payments",
  "notes_on_invoice": false,
  "active": true,
  "default_doclang": "en",
  "email_reminder": "reminder@bravo.com",
  "currency": "USD",
  "tax_type": "intax"
}

Update a contact

PUT /api/v1/clients/{id}

Create a PUT with at least the required attributes and fields you want to update. See the example above for more help.

Example

Here we will update the e-mail address and phone number of a client.

// setup the API call with the URL and the method
$request = new fsnl_api('https://www.factuursturen.nl/api/v1/clients/12345', 'PUT');

// build the post body we are going to submit
$request->buildPostBody(array(
  'phone' => '010 123 4567',
  'email' => 'johnny@bravo.com'
));

// execute the request
$request->execute();

Delete a contact

DELETE /api/v1/clients/{id}

If there are documents set for this client, like invoices, the client cannot be deleted. The API will return an error with HTTP code 403.