Butlerapp Book API

Use below endpoint to create a booking in Butlerapp system

POST {your-butlerapp-domain}api/book

Sample Payload

{
  "booking_data": {
    "bill_receiver_index": "0",
    "has_separate_bill_data": false,
    "cart_items": [
      {
        "booking": {
          "course_timespan_id": "1257",
          "quantity": "1",
          "personal_data_index": "0"
        }
      }
    ]
  },
  "form_data": {
    "form_field": {
      "course_participants": [],
      "personal_data": [
        {
          "salutation_id": "3",
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@yopmail.com",
          "mobile_phone": "0300",
          "street": "street 31",
          "postal_code": "code",
          "place": "Berlin",
          "country_id": "57"
        }
      ],
      "extra_columns": [
        {}
      ]
    },
    "consent_agreement": {
      "consents": {
        "privacy": true
      }
    },
    "form_group": {}
  }
}

Sample payload explained

booking_data.bill_receiver_index

Index of form_data.form_field.personal_data, it means if you specify 0, the first person will be bill recipient, If you have data of more than one persons in orm_data.form_field.personal_data, then you can for example specify 1, then second person in the list will become the bill recipient.

booking_data.has_separate_bill_data

If set to false, then the bill receiver and participant are same, in this example, the participant and bill recipient are the same personIf set to true, then the bill receiver and participant are not same person, then you have to provide another person who receives the bill

booking_data.cart_items.*.booking.course_timespan_id

This is ID of the course for which you are creating the booking

How to get course_timespan_id?

From the admin panel, view the course which you want to use in this booking API, for example

GET {your_butlerapp_domain}/course_timespans/1257/view

So in this case, 1257 is your course ID

booking_data.cart_items.*.booking.quantity

Here you specify the quantity of the items you gong to book

booking_data.cart_items.*.booking.personal_data_index

Here you provide the index of the person from form_data.form_field.personal_data, for whom you are going to book this course

form_data.form_field.course_participants

Leave it empty
form_data.form_fieldpersonal_data

These are the details of bill recipient/participant. Possible values for salutation_id are below1: Diverse2: Ms 3: MrCountry ID for Germany is 57All fields are required fields

form_data.form_field.extra_columns

Leave it empty

form_data.form_fieldconsent_agreement.consents

These are the consents which must be be set to true, To get the consents related to a course, call below API

GET {your_butlerapp_domain}/api/book?ftimespans={course_id}

(Note: You already know from previous steps that how to get course ID)

This API will return a huge response, we will focus only how to get the consents
body.entities.body.consents This path in the response contains all the consents which must be set to true, here the example of consents

[
  {
    attributes: {
      id: 2,
      name: 'privacy',
      website_title: 'Datenschutzbedingungen akzeptieren',
      title: 'Datenschutzbedingungen',
      is_required: 1,
      is_warning_shown: 0,
      is_recommended: 0,
      url: 'https://www.example.com/datenschutz/',
      description: '',
      table_name: 'consents',
      warning: '',
      default_value: false
    },
    presented: [],
    related: []
  }
]

You should take name of the consent, in this case name is privacy, and set it to true in the book API payload. there can be more than one consents, then you need to set all the names to true in the book API payload, for example, lets say we received two consents named privacy and agb, this is how we will use them in the book API

"consent_agreement": {
  "consents": {
    "privacy": true,
    "agb": true
  }
},

You must set this to true, this means you are accepting the consent
form_data.form_field.form_groupLeave it empty.

Some more examples

Example payload to book for two participants

Below is the example with two participants

In this example you can see that there are two cart items, one for each participant

{
  "booking_data": {
    "bill_receiver_index": "0",
    "has_separate_bill_data": false,
    "cart_items": [
      {
        "booking": {
          "course_timespan_id": "1257",
          "quantity": "1",
          "personal_data_index": "0"
        }
      },
      {
        "booking": {
          "course_timespan_id": "1257",
          "quantity": "1",
          "personal_data_index": "1"
        }
      },
    ]
  },
  "form_data": {
    "form_field": {
      "course_participants": [],
      "personal_data": [
        {
          "salutation_id": "3",
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@yopmail.com",
          "mobile_phone": "0300",
          "street": "street 31",
          "postal_code": "code",
          "place": "Berlin",
          "country_id": "57"
        },
        {
          "salutation_id": "3",
          "first_name": "Will",
          "last_name": "Smith"
        },
      ],
      "extra_columns": [
        {}
      ]
    },
    "consent_agreement": {
      "consents": {
        "privacy": true
      }
    },
    "form_group": {}
  }
}

Example payload to book with separate details for bill recipient

{
  "booking_data": {
    "bill_receiver_index": "0",
    "has_separate_bill_data": false,
    "cart_items": [
      {
        "booking": {
          "course_timespan_id": "1257",
          "quantity": "1",
          "personal_data_index": "1"
        }
      },
    ]
  },
  "form_data": {
    "form_field": {
      "course_participants": [],
      "personal_data": [
        {
          "salutation_id": "3",
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@yopmail.com",
          "mobile_phone": "0300",
          "street": "street 31",
          "postal_code": "code",
          "place": "Berlin",
          "country_id": "57"
        },
        {
          "salutation_id": "3",
          "first_name": "Will",
          "last_name": "Smith"
        },
      ],
      "extra_columns": [
        {}
      ]
    },
    "consent_agreement": {
      "consents": {
        "privacy": true
      }
    },
    "form_group": {}
  }
}