Contact Forms (Contactformulieren)

To quickly integrate contact forms, you can also use our Javascript-library.

Changelog

1.1.0 (2020-04-03)

The contact form fields are now always embedded (Velden), and updates to contact form fields are accepted with regular PUT-back semantics.

Deprecated: The separate API for contact form fields is now deprecated, and should not be used for new integrations.

Read

GET /api2/contactformulieren

List of contact forms (contactformulieren) in Recras.

This endpoint is also publicly accessible.

Example request:

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

Example response:

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

[
   {
      "id": 1,
      "naam": "Contactformulier", // (name: "Contact Form")
      "Velden": [ // (Fields)
         {
            "id": 1,
            "naam": "Bedrijf of Groepsnaam", // (name: "Company or Group Name")
            "soort_invoer": "contact.naam", // (input_type: "contact.name")
            "verplicht": false, // (required)
            "mogelijke_keuzes": null, // (possible_choices)
            "bijzonderheden_boeking": false, // (booking_particulars)
            "field_identifier": "contact.naam" // (contact.name)
         },
         {
            "id": 2,
            "naam": "Afdeling", // (name: "Department")
            "soort_invoer": "contact.afdeling", // (input_type: "contact.department")
            "verplicht": false, // (required)
            "mogelijke_keuzes": null, // (possible_choices)
            "bijzonderheden_boeking": false, // (booking_particulars)
            "field_identifier": "contact.afdeling" // (contact.department)
         }
      ]
   },
   {
      "id": 2,
      "naam": "Standaard Onlineboeking Contactformulier", // (name: "Standard Online Booking Contact Form")
      "Velden": [] // (Fields)
   },
   {
      "id": 3,
      "naam": "Kitelessen", // (name: "Kite Lessons")
      "Velden": [] // (Fields)
   }
]
Status Codes:
GET /api2/contactformulieren/(int: id)

A specific contact form.

This endpoint is also publicly accessible.

Example request:

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

Example response:

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

{
    "id": 1,
    "naam": "Contactformulier", // (name: "Contact Form")
    "Velden": [] // (Fields)
}
GET /api2/contactformulieren/(int: id)/velden

Deprecated: since version 1.1.0 this API is deprecated. All users are advised to use the Velden (Fields) field on the /contactformulieren/(int:id) API.

A list of fields (velden) of a contact form. It is also possible to request the fields with the rest of the form, use embed=Velden (Fields) for this.

This endpoint is also publicly accessible.

Example request:

GET /api2/contactformulieren/1/velden HTTP/1.1
Host: demo.recras.nl
Accept: application/json

Example response:

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

[
    {
        "id": 1,
        "contactformulier_id": 1, // (contact_form_id)
        "naam": "Bedrijf of Groepsnaam", // (name: "Company or Group Name")
        "soort_invoer": "contact.naam", // (input_type: "contact.name")
        "verplicht": false, // (required)
        "mogelijke_keuzes": null, // (possible_choices)
        "sort_order": 1,
        "bijzonderheden_boeking": false, // (booking_particulars)
        "field_identifier": "contact.naam" // (contact.name)
     },
     {
        "id": 2,
        "contactformulier_id": 1, // (contact_form_id)
        "naam": "Afdeling", // (name: "Department")
        "soort_invoer": "contact.afdeling", // (input_type: "contact.department")
        "verplicht": false, // (required)
        "mogelijke_keuzes": null, // (possible_choices)
        "sort_order": 2,
        "bijzonderheden_boeking": false, // (booking_particulars)
        "field_identifier": "contact.afdeling" // (contact.department)
     }
  ]
Status Codes:
JSON Parameters:

  • id (integer) – Unique id number of a field

  • contactformulier_id (integer) – id number of the contact form (contactformulier_id means contact_form_id)

  • naam (string) – The name of the field as set in Recras (naam means name)

  • soort_invoer (string) –

    The type of input field. Possibilities (soort_invoer means input_type):

    • contact.landcode: The ‘country’ (land) field of the Customer in Recras - a 2-letter country code according to [ISO 3611-1-](https://nl.wikipedia.org/wiki/ISO_3166-1) (contact.landcode means contact.country_code)

    • contact.naam: The ‘name’ (naam) field of the Customer in Recras - text (contact.naam means contact.name)

    • contact.afdeling: The ‘department’ (afdeling) field of the Customer - text (contact.afdeling means contact.department)

    • contact.soort_klant: The ‘customer type’ (soort_klant) field of the Customer (contact.soort_klant means contact.customer_type)

    • contact.extra: An extra field of the Customer

    • contact.website: The ‘website’ field of the Customer

    • contactpersoon.voornaam: The ‘first name’ (voornaam) field of the Contact Person in Recras - text (contactpersoon.voornaam means contact_person.first_name)

    • contactpersoon.achternaam: The ‘last name’ (achternaam) field of the Contact Person - text (contactpersoon.achternaam means contact_person.last_name)

    • contactpersoon.geslacht: The ‘gender’ (geslacht) field of the Contact Person (suggestion for presentation: select element with possible options ‘man’ (male), ‘vrouw’ (female), ‘onbekend’ (unknown)) (contactpersoon.geslacht means contact_person.gender)

    • contactpersoon.adres (contact_person.address)

    • contactpersoon.postcode (contact_person.postal_code)

    • contactpersoon.plaats (contact_person.city)

    • contactpersoon.telefoon1 (contact_person.phone1)

    • contactpersoon.telefoon2 (contact_person.phone2)

    • contactpersoon.email1

    • contactpersoon.nieuwsbrieven: To which newsletter lists (nieuwsbrieven) the contact person should be added - a list of id numbers of newsletters. See the accompanying fields newsletter_options (preference) and mogelijke_keuzes (possible_choices). (contactpersoon.nieuwsbrieven means contact_person.newsletters)

    • boeking.datum: The date (datum) on which an informatie (information) booking is created - a date string according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Dates) date notation, excluding the ‘ordinal date’ format. (boeking.datum means booking.date)

    • boeking.starttijd: The start time (starttijd) of the informatie (information) booking - a time string according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Times) time notation. Fractions of seconds are not supported. (boeking.starttijd means booking.start_time)

    • boeking.groepsgrootte: The number of persons (groepsgrootte) - a positive integer. (boeking.groepsgrootte means booking.group_size)

    • boeking.arrangement: The package (arrangement) based on which a booking should be created - a number that corresponds to an id number from the packages API.

    • tekst: A free text field (tekst means text) (suggestion for presentation: HTML input element)

    • veel_tekst: A free field with a lot of text (veel_tekst means much_text) (suggestion for presentation: HTML textarea element)

    • keuze: A choice field where multiple choices can be checked (keuze means choice) (suggestion for presentation: HTML input[type="checkbox"] element)

    • keuze_enkel: A choice field where a single choice can be checked (keuze_enkel means single_choice) (suggestion for presentation: HTML input[type="radio"] element)

  • verplicht (boolean) – (verplicht means required)

  • mogelijke_keuzes (array|null) – In case soort_invoer (input_type) is ‘keuze’ (choice) or ‘keuze_enkel’ (single_choice), this is a list of possible choices (mogelijke_keuzes). If soort_invoer (input_type) is ‘contactpersoon.nieuwsbrieven’ (contact_person.newsletters), this is a list of IDs of possible newsletters. In that case, see the JSON map newsletter_options for the names corresponding to the id numbers.

  • sort_order – Suggestion for sort order (sort ascending for consistency with presentation in Recras)

  • bijzonderheden_boeking (boolean) – Indication whether this field is included in ‘particulars’ (bijzonderheden) of the created booking (bijzonderheden_boeking means booking_particulars)

  • extra_field_name (string) – If soort_invoer (input_type) is ‘contact.extra’, this is the name of the extra field.

  • field_identifier (string) – Important for posting back Name with which the input should be sent.

Submit

POST /api2/contactformulieren/(int: id)/opslaan

Save a completed contact form in Recras. With a contact form, only the fields listed in the corresponding fields list can be saved.

This endpoint is publicly accessible. When a valid contact form is saved by a staff member (personeelslid) with the viewContact or editContact permission, the response contains a JSON object with an integer klant_id (customer_id) and optionally an integer boeking_id (booking_id) so that a reference to the customer or booking information can be made.

Example request:

POST /api2/contactformulieren/1/opslaan HTTP/1.1
Host: demo.recras.nl

{
   "contact.naam": "Lipsum BV",
   "contact.afdeling": null,
   "contactpersoon.voornaam": "Lorem",
   "contactpersoon.achternaam": "Ipsum",
   "contactpersoon.geslacht": "onbekend",
   "contactpersoon.adres": "Dolor Sit Ametstraat 42",
   "contactpersoon.postcode": "1337 VB",
   "contactpersoon.plaats": "Teststad",
   "contactpersoon.telefoon1": "0123456789",
   "contactpersoon.email1": "info@recras.nl",
   "boeking.datum": "2017-01-13",
   "boeking.starttijd": "09:00",
   "boeking.groepsgrootte": 120,
   "boeking.arrangement": 2,
   "veel_tekst_0": "Het betreft een personeelsfeest,\\nde heer Laoreet is dan 40 jaar in dienst.",
   "keuze_0": "bedrijfsuitje",
   "contact.extra[Taart]": "Monchoutaart"
}
json field_identifier:

The entered contact information. Fields with the attribute verplicht (required) must be present; other fields can be left empty by entering the value null or by not including the field in the object.

Example response:

HTTP/1.1 200 OK
statuscode 200:

Contact form accepted

statuscode 201:

Contact form accepted

statuscode 406:

Error in the input

Example response (by logged-in staff member (`personeelslid`)):

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

{
   "klant_id": 42, // (customer_id)
   "boeking_id": 130 // (booking_id)
}
JSON Parameters:

  • klant_id (integer) – The id number with which the customer (klant) was saved. This number does not have to be new; Recras tries to link identical entries. (klant_id means customer_id)

  • boeking_id (integer) – The id number of the created booking (boeking_id means booking_id)