Booking API v1

The Booking API allows retrieving real-time data of Booking details and Task details for Venue.

Note

The Booking API contains real-time data.

Terminologies

In the context of using the Booking API, here's a short description of what certain terminologies imply.

Venue

A venue is an organisation unit that registers on the Enviso Sales application for selling tickets through one or more sales channels (direct or indirect).

Organisation

An organisation is an overarching term that is used for bundling multiple venue units. In this case, multiple venue units are part of one organisation.

Order

An order is a collection of bought tickets.

Visitor

A visitor is the person who placed the order.

Guide

A guide is a person who guides visitors.

Skill

A skill assigned to a guide by the venue.

Task

A task mentions what a guide should do.

Scanned data

The data that is available after a venue has scanned the barcode of a bought ticket.

Principles

The Booking API is a REST API solution and attempts to conform to the RESTful design principles.

Note

Throughout the document, {version} stands for the first digit of the version in use.

Eg: If you are using version 1.0, {version} would mean v1

Important to know:

  • All connections must be made over HTTPS, not HTTP.

  • All the query parameters are to be passed in lowercase.

  • All date and time data in the API request/response are passed in the Venue's time zone. This can be configured from the Enviso Admin app (Settings > Locale).

    • yyyy-MM-ddTHH:mm:ss (Eg.: 1994-11-05T13:15:30)

Response status codes

The following HTTP status codes are used within the Booking API.

Code

Description

200

OK

The request was successful, resulting in everything working as expected.

201

Created

The request was successful, resulting in the creation of a new resource.

202

Accepted

The request has been accepted for processing, but processing has not been completed.

204

No Content

The request was successfully processed, and is not returning any content.

400

Bad Request

The server was unable to understand the request. The request is most likely malformed or a mandatory parameter is missing.

Note

It is recommended to make modifications in the current request and repeat the request.

401

Unauthorised

The request has not been processed because it lacks valid authentication credentials for the target resource.

If the request included valid authentication credentials, then the 401 response indicates that authorisation has been refused for the target resource.

403

Forbidden

The server understood the request but refuses to authorize it.

This probably means you did not pass the API Key (x-api-key) in your request headers.

404

Not Found

The requested resource does not exist.

The resource may be available in the future. Subsequent requests by the client are permissible.

422

Unprocessable Entity

The server understands the content type of the request entity, but was unable to process the contained instructions.

For example, this error condition may occur if validation rules to process the entity failed.

429

Too Many Requests

The server received too many request in a given amount of time.

500

Internal Server Error

The server encountered an unexpected error, which prevented it from fulfilling the request.

502

Bad Gateway

The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

503

Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Request headers

  • The request and response data is sent as JSON.

    content-type: application/json

  • The API Key is required to be passed in the HTTP Request Headers.

    x-api-key: your_api_key

  • The Tenant Key can optionally be passed in the HTTP Request Headers.

    x-tenantsecretkey: your_tenant_key

  • The Authorization header is required for all endpoints.

    authorization: Bearer SPACE your_jwt_token

Authentication

Contact Vintia support to obtain the Tenant key, API key and API secret key, which you need to start communicating to the API.

Once you have the needed information, you need to authenticate first before you'll be able to call the Booking API.

For this, you'll need to use the Authentication API.

Going live

When going from the staging environment to the production environment:

  • Use the production environment API key and API secret key of the Authentication API.

  • Use the production environment API Key and Tenant key of the Booking API.

    Note

    Contact Vintia support to get your production environment keys of the Authentication API and Booking API.

  • Change the base URL from the staging environment to the production environment.

    • Production environment: https://api.enviso.io/bookingapi

    • Staging environment: https://api.staging-enviso.io/bookingapi

Bookings

Get booking details

GET /bookingapi/v1/bookings/{id}

Get the latest real-time booking data by booking ID.

Query parameter

Name

Type

Required

Description

id

long

true

The id of booking for which you need the booking details.

Response

Success response code: 200 OK

Enum values

Parameter

Value

status

1 = confirmed

2 = cancelled

Request
var client = new RestClient("https://api.staging-enviso.io/bookingapi/v1/bookings/0");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
IRestResponse response = client.Execute(request);
Request
HttpResponse<String> response = Unirest.get("https://api.staging-enviso.io/bookingapi/v1/bookings/0")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .asString();
Request
const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.staging-enviso.io/bookingapi/v1/bookings/0");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);
Request
import http.client

conn = http.client.HTTPSConnection("https://api.staging-enviso.io/bookingapi")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("GET", "/v1/bookings/0", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response
json
{
  "id": 0,
  "status": 1,     
  "bookingDate": "2024-04-17T11:47:56.177Z",
  "visitorFirstName": "string",
  "visitorLastName": "string",
  "eventId": 0,
  "eventName": "string",
  "eventDescription": "string",
  "eventStartDate": "2024-04-17T11:47:56.177Z",
  "eventEndDate": "2024-04-17T11:47:56.177Z",
  "orderId": 0,
  "bookingLines": [
    {
      "id": 0,
      "bookingId": 0,
      "offerId": 0,
      "status": 0,    
      "numberOfVisitors": 0,
      "guideLanguage": "string",
      "visit": {
        "start": "2024-04-17T11:47:56.177Z",
        "end": "2024-04-17T11:47:56.177Z"
      }
    }
  ]
}

{
  "errors": [{
	"message": "string",
	"code": "number"
  }]
}

Tasks

Get task details

GET /bookingapi/v1/tasks/{id}

Get the latest real-time task data by task ID.

Query parameter

Name

Type

Required

Description

id

guid

true

The id of the task for which you need the booking details.

Response

Success response code: 200 OK

Enum values

Parameter

Value

status

1 = Open

2 = Awaiting Confirmation

3 = Accepted

4 = Declined

5 = Cancelled

Request
var client = new RestClient("https://api.staging-enviso.io/bookingapi/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/plain");
request.AddHeader("Authorization", "string");
request.AddHeader("x-tenantsecretkey", "string");
request.AddHeader("origin", "string");
request.AddHeader("x-api-key", "API_KEY");
IRestResponse response = client.Execute(request);
Request
HttpResponse<String> response = Unirest.get("https://api.staging-enviso.io/bookingapi/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08")
  .header("Accept", "text/plain")
  .header("Authorization", "string")
  .header("x-tenantsecretkey", "string")
  .header("origin", "string")
  .header("x-api-key", "API_KEY")
  .asString();
Request
const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.staging-enviso.io/bookingapi/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08");
xhr.setRequestHeader("Accept", "text/plain");
xhr.setRequestHeader("Authorization", "string");
xhr.setRequestHeader("x-tenantsecretkey", "string");
xhr.setRequestHeader("origin", "string");
xhr.setRequestHeader("x-api-key", "API_KEY");

xhr.send(data);
Request
import http.client

conn = http.client.HTTPSConnection("https://api.staging-enviso.io/bookingapi")

headers = {
    'Accept': "text/plain",
    'Authorization': "string",
    'x-tenantsecretkey': "string",
    'origin': "string",
    'x-api-key': "API_KEY"
    }

conn.request("GET", "/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
Response
json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "string",
  "description": "string",
  "location": "string",
  "status": 1,    
  "languages": [
    "string"
  ],
  "type": "Manual",
  "linkedBookings": [
    {
      "bookingId": 0,
      "bookingLineId": 0
    }
  ],
  "taskGuide": {
    "id": 0,
    "firstName": "string",
    "lastName": "string"
  }
}

{
  "errors": [{
	"message": "string",
	"code": "number"
  }]
}