Company public service methods

General Information

SimplyBook.me API service build on JSON-RPC remote procedure call protocol. A remote method is invoked by sending a request to a remote service using HTTPS. All transfer types are single objects, serialized using JSON. A request is a call to a specific method provided by a remote system. It must contain three certain properties:

• jsonrpc - a version of JSON-RPC protocol. Always "2.0"
• method - A String with the name of the method to be invoked.
• params - An Array of objects to be passed as parameters to the defined method.
• id - A value of any type, which is used to match the response with the request that it is replying to.

The receiver of the request must reply with a valid response to all received requests. A response must contain the properties mentioned below.

• result - The data returned by the invoked method. If an error occurred while invoking the method, this value must be null.
• error - A specified error code if there was an error invoking the method, otherwise null.
• id - The id of the request it is responding to.

Example

  Request
  {
    "jsonrpc": "2.0",
    "method": "getEventList",
    "params":[],
    "id":1
  }
  
  Response
  {
    "result": {
        "1": {
            "id": "1",
            "name": "Часовая фотосесcия",
            "duration": "60",
            "hide_duration": "0",
            "description": "<p>Если Вы хотите попробовать себя в роли модели, но не определились с образом. <br /> 5-7 отретушированных и готовых к печати фотографий + отснятый материал на диске</p>",
            "picture": "a200edab10b669225e22d2b3803a38b5.jpg",
            "is_public": "1",
            "is_active": "1",
            "position": "0",
            "is_recurring": "0",
            "picture_path": "/uploads/mib/event__picture/small/a200edab10b669225e22d2b3803a38b5.jpg",
            "price": "300.0000",
            "currency": "UAH",
            "categories": ["1"]
        },
        ...
    },
    "id": "1",
    "jsonrpc": "2.0"
  }

Example of request with error response:

  Request
  {
    "jsonrpc": "2.0",
    "method": "someNotExistingMethod",
    "params":[],
    "id":1
  }
  
  Response
  {
    "jsonrpc": "2.0",
    "id":1,
    "error": {
      "code": -32601,
      "message": "Method not found"
    }
  }

All calls of public service methods should have two additional HTTP headers:

• X-Company-Login
• X-Token an authentication token. See authentication section.

Endpoint

Use URL https://user-api.simplybook.me/ for all public service API calls.

Authentication

Using Simplybook API methods require an authentification. To authorize in Simplybook API you need to get an access key — access-token. In order to get this access-token you should call the JSON-RPC method getToken API method on https://user-api.simplybook.me/login service passing your personal API-key. You can copy your API-key at admin interface: go to the 'Plugins' link and select API plugin 'Settings'.

Methods

book

book($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId, $recurringData)

Parameters:

• $eventId Integer
• $unitId Integer
• $date String - in Y-m-d format
• $time String - in H:i:s format
• $clientData Object - eg. {name: 'Name', email: 'test@gmail.com', phone: '+38099999999'}
• $additional array|Object - additional params and fields.
• $count Integer - bookings count, min. 1 (using for group bookings batch). (optional)
• $batchId Integer - add booking to multiple bookings batch. (optional)
• $recurringData Array - make booking recurrent. (optional)

Returns Object.

Creates new booking record. Returns an object with appointment information or throw exception if booking time not available or any of required parameters missed. If appointment requires confirmation, in result object will be require_confirm = true. $startDate and $startTime specifies a date of booking and time slot. Time value should be multiple to 'timeframe' configuration of company (see getTimeframe API method). $endDate and $endTime parameters should be calculated according to service duration. However you can specify different values to make appointment longer or shorter then service configuration. Note that $endDate and $endTime should be later in time than $startDate and $startTime. If your clients located in different time zone you should specify 'client_time_offset' value in $clientData object as difference between company's time zone and client's time zone in seconds. For example if company located in city with time zone GMT+2 and customer located in city with GMT+3 then $clientTimeOffset will be -3600 seconds. You can get information about company's time zone using getCompanyInfo API method. To create batch booking you can specify either count more then 1 or valid batchId (only one parameter can be specified). You should specify an $additionalFields parameter if service requires some additional fields (see Additional fields plugin). To create a booking with promo code you should pass it as additional field. For example: {"name": "promocode", "value": "some code", "type": "text"}See example of book API method response.

See also:

• Timeframe information

---

cancelBooking

cancelBooking($id, $sign)

Parameters:

• $id Integer
• $sign String

Returns Boolean.

Cancels a booking. $sign parameter must be a string created with formula: md5($bookingId . $bookingHash . $secretKey) . You can get $bookingHash value as result of book API method call. Method return an error with code -32080 (Appointment couldn't be found) if record with specified id not exists. Methods returns an error with code -32085 (Signature error) if $sign parameter is wrong.

---

confirmBooking

confirmBooking($id, $sign)

Parameters:

• $id Integer
• $sign String

Returns Boolean.

Confirm booking. Signature is required.$sign = md5($bookingId . $bookingHash . $secretKey); Call this method from server side only

---

confirmBookingBatch

confirmBookingBatch($batchId, $batchType, $sign)

Parameters:

• $batchId Integer
• $batchType String
• $sign String

Returns Boolean.

Confirms booking batch. Signature is required.$sign = md5($batchId . $batchHash . $secret) Call this method from server side only

---

confirmBookingBatchPayment

confirmBookingBatchPayment($batchId, $batchType, $paymentProcessor, $sign)

Parameters:

• $batchId Integer
• $batchType String
• $paymentProcessor
• $sign String

Returns Boolean.

Confirms booking batch payment. Signature is required.$sign = md5($batchId . $batchHash . $secret) Call this method from server side only

---

confirmBookingCart

confirmBookingCart($cartId, $paymentProcessor, $sign)

Parameters:

• $cartId Integer - cart id
• $paymentProcessor String - payment processor name
• $sign String - signature. (md5($cartId . $cartHash . $secretKey))

Returns Boolean.

Confirm booking cart. Use it to confirm payment. Signature is required.

---

confirmBookingPayment

confirmBookingPayment($id, $paymentProcessor, $sign)

Parameters:

• $id Integer
• $paymentProcessor String
• $sign String

Returns Boolean.

Confirm booking payment. Signature is required.$sign = md5($bookingId . $bookingHash . $secretKey); Call this method from server side only

---

getBooking

getBooking($id, $sign)

Parameters:

• $id Integer
• $sign String

Returns Object.

Returns an object with details information about booking. $sign parameter must be a string created with formula: md5($bookingId . $bookingHash . $secretKey). You can get $bookingHash value as result of book API method call. Method return an error with code -32080 (Appointment couldn't be found) if record with specified id not exists. Methods returns an error with code -32085 (Signature error) if $sign parameter is wrong.

---

getBookingCart

getBookingCart($bookingIds)

Parameters:

• $bookingIds Array

Returns Object.

Returns cart information by bookings ids.cart_id and cart_hash is used to create secure signature to confirm cart payment. amount - is total amount to payment currency - cart currency cart - contains cart items. You can use them to provide information for payment system. Each item is object with following fields: id - booking id event_id - service id name - event name + start date time (use it to provide cart information for payment system) price - booking price qty - qty of bookings

---

getBookingDetails

getBookingDetails($id, $sign)

Parameters:

• $id Integer
• $sign String

Returns Object.

Returns an object with details information about booking. $sign parameter must be a string created with formula: md5($bookingId . $bookingHash . $secretKey). You can get $bookingHash value as result of book API method call. Method return an error with code -32080 (Appointment couldn't be found) if record with specified id not exists. Methods returns an error with code -32085 (Signature error) if $sign parameter is wrong.

---

getCategoriesList

getCategoriesList($isPublic)

Parameters:

• $isPublic boolean

Returns Array.

{@inheritdoc}

---

getEventList

getEventList($isVisibleOnly, $asArray)

Parameters:

• $isVisibleOnly boolean
• $asArray boolean

Returns Array.

{@inheritdoc}

---

getLocationsList

getLocationsList($isPublic, $asArray)

Parameters:

• $isPublic Boolean
• $asArray

Returns Array.

{@inheritdoc}

---

getPaymentProcessorConfig

getPaymentProcessorConfig($paymentProcessor)

Parameters:

• $paymentProcessor String

Returns Array.

Returns payment processor config

---

getPromocodeInfo

getPromocodeInfo($code)

Parameters:

• $code String

Returns Array|null.

Returns an object with detailed information about promotion by promotion code. Returns null if no promotions with specified code were not found.

---

getPromotionRewardInfo

getPromotionRewardInfo($commonPromotionId, $clientId, $hash)

Parameters:

• $commonPromotionId Integer
• $clientId Integer
• $hash String

Returns Array|null.

Returns promotion reward by common promotion id, client id and hash.

---

getRecurringDatetimes

getRecurringDatetimes($eventId, $unitId, $date, $time, $recurringData)

Parameters:

• $eventId Integer
• $unitId Integer
• $date String
• $time String
• $recurringData Array

Returns Array.

Get list of dates for recurring booking

---

getUnitList

getUnitList($isVisibleOnly, $asArray)

Parameters:

• $isVisibleOnly boolean
• $asArray boolean

Returns Array.

{@inheritdoc}

---

getUserLicenseText

getUserLicenseText()

No arguments. Returns String.

Returns user license text if user license plugin is turned on, otherwise throws exception

---

hasUpcommingPromotions

hasUpcommingPromotions()

No arguments. Returns Boolean.

Returns availability of active promotions

---

isPaymentRequired

isPaymentRequired($eventId)

Parameters:

• $eventId Integer

Returns Boolean.

Return true if event payments plugin is turned on and prices were set, else return false.

---

validatePayment

validatePayment($paymentInfo, $cartId)

Parameters:

• $paymentInfo mixed
• $cartId Integer

Returns Boolean.

Validate application payment.

---

validatePromoCode

validatePromoCode($code, $startDateTime, $eventId, $count, $clientData)

Parameters:

• $code String
• $startDateTime String
• $eventId Integer
• $count Integer
• $clientData array|Object

Returns Boolean.

Validate promotion code.Returns true in case promocode is valid otherwise throws exception with error.

---

Constants

Error codes

See Errors handling for details.

• -32001 Plugin is not activated
• -32010 Some required params are missed
• -32011 Params is not array
• -32012 Sheduler id not found
• -32015 Passed event id is not reccuren
• -32020 Sorry, you have no permissions to perform this action
• -32030 Invalid promotion code
• -32031 Promotion has expired
• -32032 Promotion is not active yet
• -32033 This promocode is not valid for selected service
• -32034 Exceed max usage limit
• -32035 Exceed max usage per customer limit'const
• -32036 This promocode is not available for datetime range
• -32051 Selected event id is not available
• -32052 Selected unit id is not available
• -32053 Selected date start is not available
• -32054 Selected time start is not available
• -32055 One or more appointments couldn't be reserved
• -32056 Booking is not allowed at this time
• -32061 Client name value is wrong
• -32062 Client email value is wrong
• -32063 Client phone value is wrong
• -32070 Additional field values are wrong
• -32080 Appointemnt couldn't be found
• -32085 Signature error
• -32090 Confirmation with this key type is not available
• -32095 Batch not found
• -32097 Unsupported payment system
• -32099 Payment failed
• -32600

  An error with this code can be thrown with one of the following messages:

  • Access denied
  • Company does not exists
• -32601 Method not found
• -32602 Invalid params
• -32603 Internal error
• -3264 Client with given id not found

---

Company params

Use these values to get configuration params for company with getCompanyParam API method.

• allow_delay_payment
• allow_event_breaktime_break

  true if service can extend over breaktime

• allow_event_day_break

  true if service can extend over closing hours

• changable_prefix_by_client
• company_timezone
• date_format
• fixed_country_prefix
• hide_sale_tax
• max_group_bookings
• max_time_till_event
• min_time_till_event
• monday_is_first_day

  true if monday specified as first day of the week in company's settings

• payment_timeout
• require_fields

  String. Client's data fields required for booking. Possible values:

  • phone - phone number is required
  • email - email address is required
  • email_phone - phone number and email address are required
• sale_tax
• send_notifications_in_client_timezone
• show_booking_page_in_client_timezone
• time_format
• timeframe

  Returns company's timeframe configuration (in minutes). Timeframe can be either 5, 10, 15, 20, 30 or 60 minutes. You can find more details about timeframe here

• user_public_timeline_type

  String. Can be one of the following values:

  • flexible
  • modern
  • flexible_week
  • modern_week
  • classic

  Please note that classic timeline type is deprecated and not supported anymore.

---

Plugin's identifiers

Plugin identifier is a string constant which represents a plugin in system. These constants used in isPluginActivated and getPluginStatuses API methods.

• advanced_notification

  Book Soon notification system plugin

• any_unit

  Any Employee selector plugin

• api

  API plugin

• approve_booking

  Approve booking plugin

• back_to_site

  Take me back home plugin

• contact_widget

  Contact widget plugin

• counter

  Visitor Counter plugin

• custom_css

  Custom CSS plugin

• data_security

  Clean history plugin

• description

  HTML description field for events

• event_category

  Service categories plugin

• event_field

  Additional fields plugin

• facebookImage

  Facebook client info plugin

• financial_dashboard

  Insights plugin

• google_analytics

  Google Adwords and analytics plugin

• google_calendar_export

  Google calendar sync plugin

• group_booking

  Group bookings plugin

• hipaa

  HIPAA plugin

• limit_bookings

  Limit bookings plugin

• location

  Unit location plugin

• mobile_app_backend

  Mobile application plugin

• multiple_booking

  Multiple bookings plugin

• news

  News plugin

• paid_events

  Accept payments plugin

• promo

  Simply Smart Promotions plugin

• recap

  Daily report plugin

• secure

  SSL plugin

• status

  Status plugin

• unit_colors

  Providers color coding plugin

• user_license

  Terms and conditions plugin

See Plugins page for description for each plugin.

---

Examples

book response

book API method returns an object which contains list of objects with short description of newly create bookings. Method returns only one item in 'bookings' array for regular appointment and more than one item for recurring or batch bookings.

 {
   "require_confirm":false,
   "bookings":[
     {
       "id":"434",
       "event_id":"7",
       "unit_id":"3",
       "client_id":"34",
       "start_date_time":"2015-12-30 13:00:00",
       "end_date_time":"2015-12-30 13:30:00",
       "is_confirmed":"1",
       "code":"h8vc14ca",
       "hash":"785cb8cce316e64765b94c05a635f4be"
     },
     {
       "id":"435",
       "event_id":"7",
       "unit_id":"3",
       "client_id":"34",
       "start_date_time":"2015-12-31 13:00:00",
       "end_date_time":"2015-12-31 13:30:00",
       "is_confirmed":"1",
       "code":"h8vc2pge",
       "hash":"8b92d634541bfd93c0830967e56f4653"
     },
     {
       "id":"436",
       "event_id":"7",
       "unit_id":"3",
       "client_id":"34",
       "start_date_time":"2016-01-04 13:00:00",
       "end_date_time":"2016-01-04 13:30:00",
       "is_confirmed":"1",
       "code":"h8vc3urb",
       "hash":"cd22a0bf183f7350e595988dd2486e5b"
     },
     {
       "id":"437",
       "event_id":"7",
       "unit_id":"3",
       "client_id":"34",
       "start_date_time":"2016-01-05 13:00:00",
       "end_date_time":"2016-01-05 13:30:00",
       "is_confirmed":"1",
       "code":"h8vc44d9",
       "hash":"53f98ff4e4a0323aa907156c59c99362"
     }
   ],
   "batch_type":"batch_recurrent_booking",
   "recurrent_batch_id":"1",
   "batch_hash":"357178bce290381bb7235080941ec143"
 } 

---

getCompanyInfo response

An example of data returned by getCompanyInfo API method.

 {
   "login": "pierrecoetzee",
   "name": "Pierre",
   "description": "Write a description about your company or about you as a service provider. You can add other service providers inside the system and each can have his own description.",
   "address1": "",
   "address2": "Storey's Gate, ",
   "city": "London",
   "country_id": "GB",
   "lat": "51.500435",
   "lng": "-0.129811",
   "email": "pierre.coe@gmail.com",
   "phone": "",
   "web": null,
   "skip_address": null,
   "logo": null,
   "address": "GB, London, Storey's Gate, ",
   "description_text": "Write a description about your company or about you as a service provider. You can add other service providers inside the system and each can have his own description.",
   "timezone": "Europe London",
   "show_in_client_timezone": false,
   "timeframe": "60",
   "timeline_type": "modern_week",
   "allow_event_day_break": "0",
   "allow_event_breaktime_break": "0"
 }

timeline_type field can be one the following values:

• flexible
• modern
• flexible_week
• modern_week
• classic
• classes

Please note that classic timeline type is deprecated and not supported anymore.

description field contains raw data of company's description which can include HTML tags. description_text field contains only text information without HTML tags.

For information about timeframe, timezone, allow_event_day_break and allow_event_breaktime_break see Company params section.

---

getPluginPromoInfoByCode response

 {
   "id": "1",
   "title": "[service\/services] with [discount]% discount!",
   "code": "yvuvugum",
   "description": "We are offering [service\/services] with an amazing [discount]% discount! We are running this deal for a limited time only.",
   "discount": "99.9999",
   "start_date": "2015-12-23",
   "expired_date": "2016-01-23",
   "sheduler_start_date": "2015-12-23",
   "sheduler_end_date": "2015-12-31",
   "sheduler_start_time": "09:00:00",
   "sheduler_end_time": "22:30:00",
   "allow_usage_count": "20",
   "fineprint_text": "Deal is limited for new clients only. Reward is claimable [client_claim_times_number] times per client. Deal is only claimable for the locations specified. Deal is cannot be combined with any other promotion. Must be redeemed prior to the expiration date shown on the deal.",
   "redemption_text": "Present your confirmation code when you want to redeem your deal. You may either to print off your confirmation email or show your confirmation code by loggin into Simplybook on your mobile phone\/Pc.\r\n[promocode]\r\n[discount]\r\n[reward]\r\n[referal_qty]",
   "headline": "[service\/services] with [discount]% discount!",
   "image": null,
   "allow_customer_count": "1",
   "show_in_catalogue": "1",
   "status": "active",
   "plugin_promo_message_id": "1",
   "common_promotion_id": "132",
   "service_ids": ["1"]
 }

service_ids contains a list of services for wich promotion discount can be applied.

---

getLocationsList response

 {
   "1": {
       "id": "1",
       "title": "location 1",
       "description": null,
       "picture": "e1e9409fe9682c78b2f8f294dc151af0.jpg",
       "address1": null,
       "address2": "Saint Margaret Street",
       "city": "London",
       "zip": null,
       "country_id": "GB",
       "lat": "51.50013000000000000000",
       "lng": "-0.12630500000000000000",
       "phone": "",
       "position": "1",
       "is_default": "1",
       "file_id": "4",
       "picture_sub_path": "\/image_files",
       "picture_path": "\/uploads\/mycompany\/image_files\/small\/e1e9409fe9682c78b2f8f294dc151af0.jpg",
       "units": ["1", "3", "4", "5"] 
   },
   ...
 }

position property of location object used for order list. units array contains list of performers ids associated with location.