Our Booking, Marketing and Customer feedback software API

Hakema.io API Introduction

The Hakema.io API is organised around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. All responses from the API will be encoded as JSON.

We support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret authentication credentials in any public website’s client-side code).

Production API URLs
https://www.hakema.net/api/...
https://app.hakema.io/api/...

Sandbox URL

https://sandbox.hakema.io/api/...

Authentication

Authentication is required by the Hakema.io API to access. You authenticate to the API through HTTP Basic Auth by providing one of your API keys in the request.

Provide the ID of the API key as the username and its password as the password. Note that there may be key-specific privileges affecting which API methods can be used with the given API key.

Your API keys carry many privileges, so remember: Keep them secret, keep them safe! In case you fear an API key has gone into wrong hands, just delete the key and get a new one.

All API requests must be made over HTTPS. Note that all requests require authentication.

curl example
$ curl https://www.hakema.net/api/service_provider/:sp_number/services.json/ \
-u 379294724df56b5afbda46992702df22:\ea83c60e44593658cb8bf3c5d6fea147

Errors

Hakema.io uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing.), and codes in the 5xx range indicate an error with the’s servers.

Attributes

code

string

Error code

message set

string

Human readable error message.

errors set

list

A list of errors, usually for which parameters were invalid, plus possible explanations.

ServiceProviders

Object: service_provider

Methods

To get information about a Service provider using the service provider number.

Note: Service Provider Numbers are allocated by the system. Only the authorised user can get information about the service provider.

GET <URL>/api/service_provider/:sp_number

Attributes

name mandatory	string Display name of the service provider
description optional	string Description about the service provider.
active optional	tinyint To check service provider is active or inactive. Values are 0 (inactive) and 1 (active).
country_name mandatory	string Name of the Country

Arguments

sp_number

required

string

identifier (url_text) of the service provider eg : “57205dd4a7b34”

Example response

service_provider : [
    {
          name : "Liikkunen" ,
          active : 1,
          description : “Liikkunen tarjoaa raskausajan liikuntaa sekä äitien vauvojen“,
          country_name : "Finland"
    }
]

Services

Object : service

This object represents services associated with a service provider. See also Service Providers.

Attributes

number mandatory	string It is Identifier for service and unique in the system.
name mandatory	string Name of the service
description optional	string Description about the service.
service_duration mandatory	int Duration for the service in minutes.
price mandatory	decimal Price of the service including VAT or TAX. It is defined in the local currency for e.g. for US it is dollars and cents and for Finland it is Euros and euro cents.
categories optional	list of category objects All the categories where this service belongs. Service may not have any category and in that case a default category is assigned.

Example Service object

{
    number : “57205dd4a7b34”,
    name : "Handwash" ,
    price : "50.00",
    service_duration : "45",
    description : "Handwash for small and personal cars",
    categories:	
               name	"Body Massage"
               number	"5747d5d3ab885"
               description	null
}

Methods
To get the services object belongs to a Service provider by using Service provider number.

GET <URL>/api/service_provider/:sp_number/services.json

Arguments

sp_number

required

string

identifier (url_text) of the service provider eg : “57205dd4a7b34”

Example response

services : [
    has_more : false ,
    servicelist :
         [
            "Service": {
                 number : “52f36cc5bd874”,
                 name : "Injury treatment and rehabilitation" ,
                 price : "30.00",
                 description : "Once the problem has been identified, which may involve muscle testing and joint assessments."
                 service_duration : "30",
                 categories : {
                              number : “57205dd4a7cvb” ,
                              name : "massage" ,
                              description: 'null'
                            }
            },
           "Service": 
           {
                  number : “52f36cc5bd874”,
                  name : "Injury treatment and rehabilitation" ,
                  price : "40.00",
                  description : "We will use a range of manual therapy techniques (including remedial massage), ultrasound, cryotherapy, stretching and rehabilitative."
                  service_duration : "30",
                  categories : 
                            { 
                              number : “57205dd4a7cvb”,
                              name : "auto" ,
                              description: 'For personal car wash"
                            }
             }     
         ]
 ]

Availabilities

This object lists available times of a service with a service provider for all the resources.

Object : availability

Attributes

availability mandatory	Text Resource availability of a service presented in structural form.
resource_number optional	string Unique identifier of the resource
start_date optional	date Start date having date format yyyy-mm-dd. If it is not provided then the default is today.
days optional	datetime Number of days to get the availability. Default is 14 days and max is 365 days.

Returns

Returns list of available times, plus has_more to indicate if more objects exists, or an error on failure.

Definition

GET <URL>/api/service_provider/:sp_number/service/:service_number/availability.json?start_date=”2017-05-25″&days=”4″

Example response

{

    "availabilities": {
        "2020-01-20": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-21": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-22": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-23": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-25": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-26": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-27": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-28": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-29": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-01-30": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-02-01": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        },
        "2020-02-02": {
            "resource_number": "584f0eae3dbc5",
            "info": [
                {
                    "price": "145.00",
                    "slot": [
                        "08:00",
                        "09:00",
                        "10:00",
                        "11:00"
                    ]
                }
            ]
        }
    }
}

Notes

Service price is in the price chosen in the account and includes VAT /Tax.

Service duration is in minutes.

Bookings

This object is using to make or cancel bookings with a service provider.

Object : booking

Attributes

sp_number mandatory	string identifier (url_text) of the service provider eg : “57205dd4a7b34”
service_number mandatory	string Unique Identifier of the service
resource_number mandatory	string Unique identifier of the resource
notes_customer optional	string Customer note
status optional	string Permitted values are CONFIRMED, PENDING, CANCELLED, NO_SHOW. If no value is supplied, it is considered CONFIRMED.
start_time mandatory	datetime Start time having date and time format
user_name mandatory	string Customer’s First and Last Name
user_email mandatory	email Customer’s email address
user_phone mandatory	phone Customer’s Phone no
pickup_time* mandatory (only when service provider category automotive)	datetime Pick time having date and time format
details* mandatory (only when service provider category automotive)	string Typically the auto registration no
price optional	decimal Price of the service including VAT or TAX. It is defined in the local currency for e.g. for US it is cents and for Finland it is euro cents.
booking_source optional	string Source of the booking for e.g. Website, API, Facebook
booking_source_info optional	string Additional information about booking source for e.g. URL or application-id
payment optional	tinyint To indicate if it was paid booking or not. Values are 0 (not paid) and 1 (paid)
send_email optional	tinyint To indicate if the system should send booking confirmation email. Values are 1 (do not send) and 0 (send). The default value is 0 ie. send booking confirmation email..

Note: The promotional values are yet not supported in the API.

Example booking object

{
    sp_number:  "545bd18ad1776",
    service_number : “83de3b9a8c24”,
    resource_number : “584f0eae3dbc5”,
    start_time : “2017-07-18 11:00”,
    price : 49.99,
    status : “CONFIRMED”,
    notes_customer : “Wants car shine Porche”,
    user_name: “Maija Mukava”,
    user_phone : “04012345678”,
    user_email : “maija@example.com”
    details: "BBX-234",
    pickup_time: "15:00"
}

Make a booking

Definition POST <URL>/api/booking/create

Response Object

request_status

mandatory

string

booking_number

mandatory

string

Unique Identifier of the booking which should be used to cancel the booking.

notes_customer

optional

string

Customer note

status

optional

string

Values are CONFIRMED, PENDING, CANCELLED, NO_SHOW.

start_time

mandatory

datetime

Start time having date and time format

end_time

mandatory

datetime

End time having date and time format

pickup_time*

mandatory

(only when service provider category automotive)

datetime

Pick time having time format

details*

mandatory

(only when service provider category automotive)

string

Typically the auto registration number supplied by the customer in the booking request.

price

mandatory

decimal

Price of the service including VAT or TAX. It is defined in the local currency for e.g. for US it is dollar and cents and for Finland it is euro and euro cents.

booking_source

optional

string

Source of the booking for e.g. Website, API, Facebook

booking_source_info

optional

string

Additional information about booking source for e.g. URL or application-id

payment

optional

tinyint

To indicate if it was paid booking or not. Values are 0 (not paid) and 1 (paid)

Example Return booking object.

 
{
    "request_status":"success",
    "booking_number":"5a947a550049e",
    "booking_refernce":"2KKRWRJB",
    "status":"CONFIRMED",
    "details":"BBX-2341",
    "pickup_time":"15:00",
    "notes_customer":null,
    "start_time":"2018-02-28 09:30:00",
    "end_time":"2018-02-28 10:00:00",
    "created_by":"customer",
    "payment":"0",
    "source":"API",
    "source_info":null,
    "price":"30.50"
 }

Confirm an existing booking

Arguments:

booking_number

mandatory

int

The number of the booking object.

Definition POST <URL>/api/booking/:booking_number/confirm

Example response

{
      booking_number : “xxxxxxxxx”,
      status : “CONFIRMED”,
}

Cancel a booking

Arguments:

booking_number

mandatory

int

Unique number of the booking object.

Definition POST <URL>/api/booking/:booking_number/cancel

Example response

{
      booking_number : “xxxxxxxxx”,
      status : “CANCELLED”,
}

number mandatory	string It is a unique Identifier for resource.
name mandatory	string Name of the resource
mobile optional	string Mobile number
email optional	string Email id
description optional	string Description of the resource

Hakema.io API Introduction

Authentication

Errors

Attributes

ServiceProviders

Object: service_provider

Attributes

Services

Object : service

Categories

Resources

Availabilities

Bookings

What is Hakema.io

Features

Product Demos

Businesses

Company

Support

Socialise with us

number mandatory	string It is Identifier for category other than id.
name mandatory	string Name of the category
description optional	string Description of the category