# Settings and ref-data

Load settings and ref-data when your booking UI starts, and cache them for the
session. They change rarely. Settings say how booking is configured for the
account. Ref-data lists the services and resources that can be booked.

## Fetch settings

```
GET /settings/
```

Returns the booking configuration for the account.

**Response 200**

```json
{
  "currencyCode": "SEK",
  "preferredE164CountryCode": "46",
  "stripePublicKey": "pk_live_...",
  "features": {
    "EnableDiscountVouchers": true,
    "EnableEcomPayments": true,
    "EnableCompanyBooking": true,
    "EnableVehicleBooking": true
  },
  "customTexts": { "customer.name": "Namn" },
  "prefs": {
    "timeZone": "Europe/Stockholm",
    "locale": "sv_SE",
    "web_companyName": "Beauty Parlour STHLM",
    "web_addressLine1": "Regeringsgatan 67",
    "web_area": "Stockholm",
    "web_bookingMaxDaysInAdvance": "90",
    "web_minTimeBeforeBooking": 1,
    "web_bookingInterval": 15,
    "web_useSmsVerification": false,
    "web_requireEmail": false,
    "web_requirePNo": false,
    "web_requireVehicleRegNo": false,
    "web_allowMultipleServices": false,
    "web_resourceLabel": "Person"
  }
}
```

The example is shortened. `prefs` contains many more keys. The most useful ones
for a custom client:

| Preference | Meaning |
| --- | --- |
| `web_bookingMaxDaysInAdvance` | How many days ahead booking is open |
| `web_minTimeBeforeBooking` | Minimum hours between now and the slot |
| `web_useSmsVerification` | Bookings are confirmed with an SMS PIN code |
| `web_requireEmail`, `web_requirePNo`, `web_requireVehicleRegNo`, `web_requireOrgNo` | Which customer fields are required |
| `web_allowMultipleServices` | The customer may pick more than one service |
| `web_resourceLabel` | What the account calls its resources, for example "Person" |
| `web_allowCancellation`, `web_cancelUpToMinutes` | Whether and until when customers may [cancel a booking](https://developers.cliento.com/docs/widget-api/manage-booking.md) |
| `web_allowPayOnSite` | Customers may choose to pay at the visit instead of online, see [Payments](https://developers.cliento.com/docs/widget-api/payments.md) |
| `web_requiresCaptcha` | Booking requests need a [captcha](https://developers.cliento.com/docs/widget-api.md#captcha) token |

The `features` object tells you which account features are active, for example:

- `EnableCompanyBooking`: company booking, with organisation fields
- `EnableVehicleBooking`: vehicle booking, with a registration number field
- `EnableEcomPayments`: online payments
- `EnableDiscountVouchers`: discount vouchers

`stripePublicKey` is the Stripe publishable key. Load Stripe.js with it when the
account takes card payments, see [Payments](https://developers.cliento.com/docs/widget-api/payments.md#stripe).

## Fetch ref-data

```
GET /ref-data/
```

Returns the bookable services and resources.

**Response 200**

```json
{
  "services": [
    {
      "serviceId": 68811,
      "name": "Women's haircut",
      "group": "Haircuts",
      "description": "Consultation, wash, cut and a simple style.",
      "minDuration": 45,
      "maxDuration": 45,
      "minPrice": 595.0,
      "maxPrice": 595.0,
      "priceFrom": false,
      "addon": false,
      "bookingType": "SimpleBooking",
      "prefs": {},
      "attributes": {},
      "classBooking": false
    }
  ],
  "resources": [
    {
      "id": 12816,
      "name": "Anna B.",
      "group": "Staff",
      "title": "Salon manager & hairdresser",
      "presentation": "Anna has been cutting and colouring for over 15 years and loves natural shades.",
      "prefs": {},
      "attributes": {},
      "hashId": "Q45V5W"
    }
  ],
  "resourceMappings": {
    "12816:68811": {
      "serviceId": 68811,
      "serviceDuration": 45,
      "afterTime": 0,
      "price": 595.0,
      "priceEvening": 0.0,
      "priceHoliday": 0.0,
      "customValues": false,
      "webShowInBooking": true,
      "webAllowBooking": true,
      "webShowDuration": true,
      "addon": false
    }
  },
  "addonMappings": [
    { "srvId": 68811, "addonSrvIds": [68809, 68808, 68810] }
  ]
}
```

The example is shortened to one entry per list.

A **service** is a thing the customer can book. Services with `addon` set to `true`
cannot be booked on their own, they are added on top of another service.
`minDuration`, `maxDuration`, `minPrice` and `maxPrice` can be `null` when the
duration or price is set per resource in the resource mappings instead. The
service preference `web_paymentRequired` tells you that booking the service
requires [online payment](https://developers.cliento.com/docs/widget-api/payments.md).

A **resource** is the person or thing that performs the service. A resource has
two ids. The slots request takes the numeric `id`, as `resIds`. The `hashId`
comes back in the slots response. It also goes in the path of the custom fields
endpoint. The resource preference `web_paymentEnabled`
tells you whether the resource can take online payment.

**Resource mappings** connect the two. The key is `{resourceId}:{serviceId}`.
A resource can perform a service when a mapping exists with `webAllowBooking`
set to `true`. Use `webShowInBooking` to decide if the combination should be
visible in your UI. The mapping can override the duration and price of the
service for that specific resource.

**Addon mappings** list which addon services (`addonSrvIds`) can be added to a
main service (`srvId`).

## Fetch custom fields

```
GET /custom-fields/resource/{resourceHashId}?srvIds={serviceIds}
```

Some accounts collect extra information in the booking form. Fetch the custom
fields for the selected resource and services before you show your customer
form.

**Request**

| Parameter | Required | Description |
| --- | --- | --- |
| `resourceHashId` | Yes | The `hashId` of the resource, from [ref-data](#fetch-ref-data) |
| `srvIds` | Yes | Comma separated service ids |

**Response 200**

```json
{ "customFields": [] }
```

An empty list means there are no extra fields. When fields exist, each entry
looks like this (example derived from the API schema):

```json
{
  "customFields": [
    {
      "key": "cf_1",
      "label": "Allergies",
      "type": "text",
      "required": false,
      "placeholder": "",
      "helpText": "",
      "options": []
    }
  ]
}
```

Send the customer's answers in the `customFields` list of the
[customer call](https://developers.cliento.com/docs/widget-api/booking.md#add-customer-details).