Quick start

This guide walks you through your first call to the Booking Engine API. You will set up OAuth 1.0 signing, open a session with the Create a new session endpoint, and use the returned identifier for the rest of the funnel.

No credentials yet? Import the API collections and run any request against the mock environment straight away, with no credentials. Add your OAuth 1.0 credentials when you are ready to call the live API.

Prerequisites

Get the following from D-EDGE before starting:

OAuth 1.0 credentials: consumer key, consumer secret, token key, and token secret.
API base URL: the base URL for your environment.
Booking Engine ID: the booking engine you integrate against.

All are delivered during the build step of your integration journey, after the partnership agreement.

Install an OAuth 1.0 library

Use a battle-tested library to handle the signing. Skip this step if you only use cURL.

npm install oauth-1.0a

pip install requests-oauthlib

composer require guzzlehttp/oauth-subscriber

dotnet add package RestSharp

<dependency>
    <groupId>oauth.signpost</groupId>
    <artifactId>signpost-commonshttp4</artifactId>
    <version>2.1.1</version>
</dependency>

Create a session

Send a POST to the Create a new session endpoint with the search context. The full field requirements are documented in the Reference.

curl --request POST \
  --url https://{apiBaseUrl}/v2/session \
  --header 'Authorization: OAuth oauth_consumer_key="YOUR_CONSUMER_KEY",
    oauth_token="HOTEL_TOKEN_KEY",
    oauth_signature_method="HMAC-SHA1",
    oauth_timestamp="1714128000",
    oauth_nonce="abc123",
    oauth_version="1.0",
    oauth_signature="..."' \
  --header 'Content-Type: application/json' \
  --data '{
    "engineId": "YOUR_ENGINE_ID",
    "guestSelectionMode": "Default",
    "display": {"culture": "en-GB", "currency": "EUR", "countryCode": "GB"},
    "context": {
      "stayPeriod": {"arrivalDate": "YYYY-MM-DD", "departureDate": "YYYY-MM-DD"},
      "guests": [{"adults": 2}],
      "selectedHotelId": "<hotelId>"
    }
  }'

import OAuth from "oauth-1.0a";
import crypto from "crypto";

const oauth = OAuth({
  consumer: {
    key: process.env.DEDGE_CONSUMER_KEY,
    secret: process.env.DEDGE_CONSUMER_SECRET,
  },
  signature_method: "HMAC-SHA1",
  hash_function(base_string, key) {
    return crypto.createHmac("sha1", key).update(base_string).digest("base64");
  },
});

const token = {
  key: process.env.DEDGE_TOKEN_KEY,
  secret: process.env.DEDGE_TOKEN_SECRET,
};

const url = "https://{apiBaseUrl}/v2/session";
const body = {
  engineId: "YOUR_ENGINE_ID",
  guestSelectionMode: "Default",
  display: { culture: "en-GB", currency: "EUR", countryCode: "GB" },
  context: {
    stayPeriod: { arrivalDate: "YYYY-MM-DD", departureDate: "YYYY-MM-DD" },
    guests: [{ adults: 2 }],
    selectedHotelId: "<hotelId>",
  },
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    ...oauth.toHeader(oauth.authorize({ url, method: "POST" }, token)),
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

const session = await response.json();
console.log(response.status, session);

import os
from requests_oauthlib import OAuth1Session

session = OAuth1Session(
    client_key=os.environ["DEDGE_CONSUMER_KEY"],
    client_secret=os.environ["DEDGE_CONSUMER_SECRET"],
    resource_owner_key=os.environ["DEDGE_TOKEN_KEY"],
    resource_owner_secret=os.environ["DEDGE_TOKEN_SECRET"],
)

response = session.post(
    "https://{apiBaseUrl}/v2/session",
    json={
        "engineId": "YOUR_ENGINE_ID",
        "guestSelectionMode": "Default",
        "display": {"culture": "en-GB", "currency": "EUR", "countryCode": "GB"},
        "context": {
            "stayPeriod": {"arrivalDate": "YYYY-MM-DD", "departureDate": "YYYY-MM-DD"},
            "guests": [{"adults": 2}],
            "selectedHotelId": "<hotelId>",
        },
    },
)

print(response.status_code)
print(response.json())

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Subscriber\Oauth\Oauth1;

$stack = HandlerStack::create();

$middleware = new Oauth1([
    'consumer_key'    => getenv('DEDGE_CONSUMER_KEY'),
    'consumer_secret' => getenv('DEDGE_CONSUMER_SECRET'),
    'token'           => getenv('DEDGE_TOKEN_KEY'),
    'token_secret'    => getenv('DEDGE_TOKEN_SECRET'),
]);

$stack->push($middleware);

$client = new Client([
    'base_uri' => 'https://{apiBaseUrl}/',
    'handler'  => $stack,
    'auth'     => 'oauth',
]);

$response = $client->post('v2/session', [
    'json' => [
        'engineId'          => 'YOUR_ENGINE_ID',
        'guestSelectionMode' => 'Default',
        'display'           => ['culture' => 'en-GB', 'currency' => 'EUR', 'countryCode' => 'GB'],
        'context'           => [
            'stayPeriod'     => ['arrivalDate' => 'YYYY-MM-DD', 'departureDate' => 'YYYY-MM-DD'],
            'guests'         => [['adults' => 2]],
            'selectedHotelId' => '<hotelId>',
        ],
    ],
]);

echo $response->getStatusCode() . "\n";
echo $response->getBody();

using RestSharp;
using RestSharp.Authenticators.OAuth;

var options = new RestClientOptions("https://{apiBaseUrl}")
{
    Authenticator = OAuth1Authenticator.ForProtectedResource(
        consumerKey: Environment.GetEnvironmentVariable("DEDGE_CONSUMER_KEY"),
        consumerSecret: Environment.GetEnvironmentVariable("DEDGE_CONSUMER_SECRET"),
        token: Environment.GetEnvironmentVariable("DEDGE_TOKEN_KEY"),
        tokenSecret: Environment.GetEnvironmentVariable("DEDGE_TOKEN_SECRET"),
        signatureMethod: OAuthSignatureMethod.HmacSha1)
};
var client = new RestClient(options);

var request = new RestRequest("/v2/session", Method.Post);
request.AddJsonBody(new
{
    engineId = "YOUR_ENGINE_ID",
    guestSelectionMode = "Default",
    display = new { culture = "en-GB", currency = "EUR", countryCode = "GB" },
    context = new
    {
        stayPeriod = new { arrivalDate = "YYYY-MM-DD", departureDate = "YYYY-MM-DD" },
        guests = new[] { new { adults = 2 } },
        selectedHotelId = "<hotelId>"
    }
});

var response = await client.ExecuteAsync(request);
Console.WriteLine(response.StatusCode);
Console.WriteLine(response.Content);

import com.fasterxml.jackson.databind.ObjectMapper;
import oauth.signpost.OAuthConsumer;
import oauth.signpost.commonshttp.CommonsHttpOAuthConsumer;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;

import java.util.List;
import java.util.Map;

OAuthConsumer consumer = new CommonsHttpOAuthConsumer(
    System.getenv("DEDGE_CONSUMER_KEY"),
    System.getenv("DEDGE_CONSUMER_SECRET")
);
consumer.setTokenWithSecret(
    System.getenv("DEDGE_TOKEN_KEY"),
    System.getenv("DEDGE_TOKEN_SECRET")
);

ObjectMapper mapper = new ObjectMapper();
String body = mapper.writeValueAsString(Map.of(
    "engineId", "YOUR_ENGINE_ID",
    "guestSelectionMode", "Default",
    "display", Map.of("culture", "en-GB", "currency", "EUR", "countryCode", "GB"),
    "context", Map.of(
        "stayPeriod", Map.of("arrivalDate", "YYYY-MM-DD", "departureDate", "YYYY-MM-DD"),
        "guests", List.of(Map.of("adults", 2)),
        "selectedHotelId", "<hotelId>"
    )
));

HttpPost request = new HttpPost("https://{apiBaseUrl}/v2/session");
request.setEntity(new StringEntity(body, "UTF-8"));
request.setHeader("Content-Type", "application/json");
consumer.sign(request);

try (CloseableHttpClient client = HttpClients.createDefault()) {
    client.execute(request);
}

Use the session

A successful response returns the session, including the sessionId. Carry that identifier in the path of every following call, for example to search available rooms:

curl --request GET \
  --url 'https://{apiBaseUrl}/v2/{sessionId}/search/rooms' \
  --header 'Authorization: OAuth ...'

From here, follow the funnel: search, describe, build the basket, quote, and confirm. Each stage is documented in the Reference.

Common issues

Status	Likely cause	Where to look
`401`	Signing issue: invalid credentials, clock drift, or reused nonce	Authentication
`400`	Validation error: malformed body or missing field	Responses
`400` with `Code: InvalidSessionId`	Unknown `sessionId`, or the session expired	Responses

Next steps

Reference

Every endpoint, grouped by stage of the funnel.

Use cases

Six patterns, from conversational agents to branded confirmation pages.

Best practices

Patterns to build the funnel responsibly and run reliably at scale.

Get started

Build

Resources

Prerequisites

Install an OAuth 1.0 library

Create a session

Use the session

Common issues

Next steps

Reference

Use cases

Best practices

​Prerequisites

Install an OAuth 1.0 library

Create a session

Use the session

​Common issues

​Next steps

Reference

Use cases

Best practices

Prerequisites

Common issues

Next steps