Customers (Klanten)¶

Create¶

POST /api2/klanten¶

Create a new contact of type klant (customer).

Example request:
POST /api2/klanten HTTP/1.1
Host: demo.recras.nl
Accept: application/json

{
   "naam": "Voorbeeldgroep", // (name: "Example Group")
   "adres": "Teststraat 1", // (address: "Test Street 1")
   "postcode": "1337 XD", // (postal_code)
   "plaats": "Teststad", // (city: "Test City")
   "provinciecode": "NL-NH", // (province_code)
   "website": "http://www.example.com",
   "bedrijf_id": 1, // (company_id)
   "soort_klant": "Familie", // (customer_type: "Family")
   "afdeling": null, // (department)
   "factuur_adressering": null, // (invoice_addressing)
   "contactpersonen": [ // (contact_persons)
      {
         "id": 15,
         "hoofdcontact": false // (main_contact)
      },
      {
         "voornaam": "Test", // (first_name)
         "achternaam": "Contactpersoon", // (last_name: "Contact Person")
         "geslacht": "man", // (gender: "male")
         "aanhef": null, // (salutation)
         "adres": "Teststraat 1", // (address: "Test Street 1")
         "postcode": "1337 XD", // (postal_code)
         "plaats": "Teststad", // (city: "Test City")
         "telefoon1": "0123456789", // (phone1)
         "email1": "test@example.com",
         "hoofdcontact": true // (main_contact)
      }
   ],
   "extra_fields": [
      {
         "name": "Shoe size",
         "type": "number",
         "value": 42,
      }
   ]
}
json string naam:

The name of the customer (naam means name)

json string adres:

The address of the customer (adres means address)

json string postcode:

(postcode means postal_code)

json string plaats:

(plaats means city)

json string provinciecode:

The ISO 3166-2 province code, used for statistics (provinciecode means province_code)

json string website:

The website of the customer

json int bedrijf_id:

id number of a Company (Bedrijf) in Recras to which this Customer (Klant) belongs; the default company is entered if this field is left empty. (bedrijf_id means company_id)

json string soort_klant:

A customer type (soort_klant) as specified for the Company (Bedrijf)

json string afdeling:

(afdeling means department)

json string factuur_adressering:

The address to be shown on the invoice, if different from the customer address. (factuur_adressering means invoice_addressing)

json array contactpersonen:

Required A list of one or more contact persons (contactpersonen); these can already exist in Recras or be new entries.

json boolean contactpersonen.hoofdcontact:

Required for each contact person (contactpersoon), it must be indicated whether this contact person is the main contact person (hoofdcontactpersoon) of this customer. There can only be 1 main contact person per customer.

json array extra_fields:

Array of extra fields. type can be one of the following: text, number, date, singlechoice, multiplechoice. When type is number, value is of type integer. When type is date, value is an ISO 8601 formatted date. When type is multiplechoice, value is an array of string values.

If an existing contact person is linked:

json int contactpersonen.id:

id number of the contact person (contactpersoon)

If a new contact person is entered (see also /contactpersonen (contact_persons))

json string voornaam:

First name (voornaam) of contact person

json string achternaam:

(achternaam means last_name)

json string geslacht:

Gender (geslacht) of contact person, possibilities are ‘man’ (male), ‘vrouw’ (female), ‘onbekend’ (unknown)

json string aanhef:

Salutation (aanhef) to be used. If left empty, the default salutation is used.

json string adres:

(adres means address)

json string postcode:

(postcode means postal_code)

json string plaats:

(plaats means city)

json string telefoon1:

(telefoon1 means phone1)

json string telefoon2:

(telefoon2 means phone2)

json string email1:

json string email2:

Example response:
HTTP/1.1 201 Created
Content-Type: application/json

{
   "id": 83,
   "type": "klant", // (customer)
   "displaynaam": "Voorbeeldgroep", // (display_name: "Example Group")
   "naam": "Voorbeeldgroep", // (name: "Example Group")
   "adres": "Teststraat 1", // (address: "Test Street 1")
   "postcode": "1337 XD", // (postal_code)
   "plaats": "Teststad", // (city: "Test City")
   "provinciecode": "NL-NH", // (province_code)
   "website": "http://www.example.com",
   "bedrijf_id": 1, // (company_id)
   "soort_klant": "Familie", // (customer_type: "Family")
   "afdeling": null, // (department)
   "factuur_adressering": null // (invoice_addressing)
}

Status Codes:

201 Created – Customer created (Klant aangemaakt)
200 OK – Entered data has been merged with an existing customer (Ingevoerde gegevens zijn samengevoegd met een bestaande klant)
406 Not Acceptable – Error in the input (Fout in de invoer)
403 Forbidden – User does not have the editContact permission (Gebruiker heeft het recht editContact niet)

Read¶

GET /api2/klanten¶

List of contacts of type ‘klant’ (customer) in Recras.

Example request:

GET /api2/klanten HTTP/1.1
Host: demo.recras.nl
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "id": 62,
      "type": "klant", // (customer)
      "displaynaam": "Pascal en Corry en kids", // (display_name: "Pascal and Corry and kids")
      "naam": "Pascal en Corry en kids", // (name: "Pascal and Corry and kids")
      "adres": null, // (address)
      "postcode": null, // (postal_code)
      "plaats": null, // (city)
      "provinciecode": null, // (province_code)
      "website": null,
      "bedrijf_id": 1, // (company_id)
      "soort_klant": null, // (customer_type)
      "afdeling": null, // (department)
      "factuur_adressering": null // (invoice_addressing)
   },
   {
      "id": 17,
      "type": "klant", // (customer)
      "displaynaam": "Gemeente Appingedam", // (display_name: "Municipality Appingedam")
      "naam": "Gemeente Appingedam", // (name: "Municipality Appingedam")
      "adres": "Testraat 23", // (address: "Test Street 23")
      "postcode": "8291KS", // (postal_code)
      "plaats": "Assen", // (city)
      "provinciecode": "NL-DR", // (province_code)
      "website": "",
      "bedrijf_id": 2, // (company_id)
      "soort_klant": "", // (customer_type)
      "afdeling": "", // (department)
      "factuur_adressering": "" // (invoice_addressing)
   }
]

Status Codes:

200 OK – OK

Query Parameters:

id> (integer) – The smallest id-value to allow in the selection. New in v1.1.0

GET /api2/klanten/(int: id)¶

A specific customer (klant).

The returned object contains a field contactpersonen (contact_persons), which contains a list of contact person objects. The first of these contact persons is the main contact person (hoofdcontactpersoon) of this contact.

Example request:

GET /api2/contacten/17 HTTP/1.1
Host: demo.recras.nl
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "id": 17,
   "type": "klant", // (customer)
   "displaynaam": "Gemeente Appingedam", // (display_name: "Municipality Appingedam")
   "naam": "Gemeente Appingedam", // (name: "Municipality Appingedam")
   "adres": "Testraat 23", // (address: "Test Street 23")
   "postcode": "8291KS", // (postal_code)
   "plaats": "Assen", // (city)
   "provinciecode": "NL-DR", // (province_code)
   "website": "",
   "bedrijf_id": 2, // (company_id)
   "soort_klant": "", // (customer_type)
   "afdeling": "", // (department)
   "factuur_adressering": "", // (invoice_addressing)
   "contactpersonen": [ // (contact_persons)
      {
         "id": 15,
         "voornaam": "Janny", // (first_name)
         "achternaam": "Jansen", // (last_name)
         "geslacht": "man", // (gender: "male")
         "aanhef": null, // (salutation)
         "adres": "Testraat 23", // (address: "Test Street 23")
         "postcode": "8291KS", // (postal_code)
         "plaats": "Assen", // (city)
         "telefoon1": null, // (phone1)
         "telefoon2": null, // (phone2)
         "email1": null,
         "email2": null,
         "hoofdcontact": true // (main_contact)
      }
   ]
}

Status Codes:

200 OK – OK
404 Not Found – No package (arrangement) with this id

Update¶

PUT /api2/klanten/(int: id)¶

Update an existing customer (klant).

The usage of this endpoint is almost identical to KlantenCreate_ <creating new customers>. Note that if the field contactpersonen (contact_persons) is specified, the list of contact persons must be specified exactly as it should be in Recras.

Changelog¶

1.1.0:: Added the id> parameter to the customers list.
0.1.0:: Old, basically unversioned API. The documentation may be outdated

Customers (Klanten)¶

Create¶

Read¶

Update¶

Changelog¶

Recras API

Navigation

Related Topics