Deem Fource Alliance Open API (Beta)
Overview
Deem provides the capability to integrate its state-of-the art Travel product with any other solution. Under the Deem Fource Alliance Program, the integration is done via a set of RESTful API. Through Deem's Open API following a wide variety of industry open standards, a Deem partner can build an integration that would allow for seamless flow of data from Deem Work Fource (travel booking technology application) to their solution.
Since new Travel bookings are always made, and older Travel bookings are often modified or canceled, a constant flow of data is expected. Depending on how frequently the API is called to download data from Deem and imported, the user will be able to see all transactions corresponding to their booking in their downstream application, creating a seamless experience.
The Deem Fource Alliance Open API provides a set of operations and resources that allow:
- Fetch itinerary data for all users for a common customer
- Fetch itinerary data for a particular user for a common customer
- Filter any data by dates
- Get historical details for a booked itinerary
- Download a pdf version of the booking confirmation that could be used as a receipt
Endpoint
The Deem Open REST API under the Deem Fource Alliance Program will be provided by the following RESTful endpoint:
Authentication
Authentication to the API is performed via standard OAuth. Partner will have to establish an OAuth session with Deem for subsequent api calls. OAuth key exchange will be part of the initial client setup on Deem side, in addition to a tenant id unique to each partner using our APIs.
API Versioning
Deem APIs are evolving over time, with the Deem Fource Alliance API adding new fields as requested by our API partners. That makes it difficult to keep it backwards compatible. However, all Deem APIs endpoints are versioned. A call to a specific version is idempotent in returning the schema of the response.
In other words, Deem guarantees that the calls made with a specific major-minor version combination will always return the same object structure at all times in the future.
Versions are part of the REST URI, and applies to all resources. The version is mandatory for all resources except the health check resource, and a call without a version will result in an HTTP 406 error code.
Clients must specify the minimum major and minor version of a resource they would like to receive. The server agrees to not send back a version earlier than this, but can send back a more recent patch version. The full version number will be exposed to the client as a version
parameter in the response Content-Type
header.
Version in the API
Version is the first path parameter, immediately following the Deem Fource Alliance endpoint:
https://api.deem.com/alliance/{version}/
Path Parameters
Parameter | Description | Required |
---|---|---|
| The version of the API | Yes |
Version number format
Client request format |
| example: |
---|---|---|
Server response format |
| example:
|
| potentially backward incompatible updates |
---|---|
| backward compatible updates |
| bug fixes |
Sample Request
curl -H “x-deem-tenant-id: acmepartners” \ “https://api.deem.com/alliance/v1.3/site/wayne/user/batman/trip/”
Client-Server Contract
Deem Alliance REST API adheres to the following principles and assumptions wrt versioning, and expects clients of the API to follow suit:
Deem API |
|
---|---|
API partners |
|
Redirection and URI changes
As resources mature, resource URIs will naturally evolve. When new versions of a resources are introduced that change the URIs of existing resources (but not the resources themselves), the server will send a redirect response and the client must send an identical request to the new resource location.
Sample request-response
For example, in version 1.1 of the Open Alliance, the receipt URI might change from
(v1.0) /alliance/trip/{trip_uuid}/receipt --> (v1.1) /alliance/site/{site_id}/user/{user_id}/trip/{trip_uuid}/receipt
This would result in the following HTTP interaction:
--> GET /alliance/v1.0/trip/asdd-123sdaf-asdf-12asdf/receipt HTTP/1.1 Host: api.deem.com <-- HTTP/1.1 301 Moved Permanently Location: https://api.deem.com/alliance/v1.1/site/wayne/user/batman/trip/asdd-123sdaf-asdf-12asdf/receipt --> GET https://api.deem.com/alliance/v1.1/site/wayne/user/batman/trip/asdd-123sdaf-asdf-12asdf/receipt HTTP/1.1 Host: api.deem.com <-- HTTP/1.1 200 OK <response body/>
Requests
Methods
All of the requests under the Deem Alliance Open API are HTTP GET requests without a request body.
Headers
All requests require authentication headers, and an Accept header.
Header | Header type | Description | Format/Validation | Required |
---|---|---|---|---|
x-deem-tenant-id | Authentication | ID of the Open Alliance partner/tenant | Valid tenant id received from Deem | Yes |
Accept | Response Type | Media type(s) acceptable for the response. |
| Yes |
Request Parameters: Time Interval
Requests that return a data collection can be filtered by a time interval. The time interval is specified by the following request parameters:
Parameter | Description | Required | Default |
---|---|---|---|
| Starting time from which trips booked or modified will be returned | Yes | N/A |
| End time till which trips booked or modified will be returned | Optional | Current time |
The format of the query parameters is driven by the ISO 8601 with three major components as described below. Any date params not adhering to the specs below will result in an HTTP error code 412. More details in the Error Handling section.
Date
YYYY-MM-DD or YYYYMMDD
The Date part represents a calendar date, with the following three subcomponents that may or may not be separated by a hyphen.
- [YYYY] indicates a four-digit year, 2000 through 9999.
- [MM] indicates a two-digit month of the year, 01 through 12.
- [DD] indicates a two-digit day of that month, 01 through 31.
For example, the 5th of March, 2018 may be represented as either "2018-03-05" in the extended format or "20180305" in the basic format.
Time
hh:mm:ss or hhmmss
The Time part uses a 24-hour clock system, and is separated from the Date time by the letter T. The following three components make up the time:
- [hh] refers to a zero-padded hour between 00 and 24 (where 24 is only used to denote midnight at the end of a calendar day).
- [mm] refers to a zero-padded minute between 00 and 59.
- [ss] refers to a zero-padded second between 00 and 60 (where 60 is only used to denote an added leap second). This may be ommitted to mean the 0th second of a minute.
Time Zone
Z or ±hh:mm or ±hh
Time Zone is represented as UTC or with an offset from UTC, with the location unspecified.
Since the tenants and Deem can be in different timezones, time zone is a mandatory part to avoid any ambiguity. In order to make things explicit, the letter Z can designate when the Time Zone is UTC. UTC may also be represented with a +00:00 or +00, but not with a -00:00 or -00.
Examples
Time Zone UTC: "10:10 UTC" is represented as 10:10Z or 1010Z or 10:10+00:00 or 1010+00.
Time Zone non-UTC: "3:10 PDT" is represented as 03:10-07:00 or 0310-07.
Full Time: The following two repsesent the same time:
2018-03-15T03:48:44-07:00
20180315T034844-07
Maximum Time Interval
The amount of Travel booking data within a time interval depends on the number of users and the prolificity of the travelers.
For continuous flow of Travel booking data from Deem to the Consumer, tenants will have to call the Deem API at regular intervals, ranging from a few minutes to a few hours. There is a limit on the maximum time interval a request can support, which is equal to 7 days. A time interval greater than that will produce an HTTP error code 412. More details in the Error Handling section.
Pagination
For all API requests that return a collection resource, the results can be paginated. The optional page_size
parameter sets the maximum number of elements to return in a reponse. The default is 20 and the maximum is 100.
The start_index
parameter becomes mandatory after the first page.
Parameter | Description | Required | Default |
---|---|---|---|
| Starting time from which trips booked or modified will be returned | No | 0 |
| End time till which trips booked or modified will be returned | No | 20 |
The response returns the page_size
, start_index
, as well as a next_page
element, which will contain the URI for requesting the next page.
Rate Limiting
Deem enforces a time-based limit on the number of requests per tenant on the REST API. This policy prevents tenants from overloading the system and monopolizing Deem system resources.
There is also a separate limit on concurrent requests per tenant. Once either the time-based or concurrent quota is reached, any REST calls for that tenant will return in an error with an HTTP error code of 429. More details in the Error Handling section. There will be a blocking time during which no further requests can be made for that tenant id.
Response
HTTP Status
The success or failure of each HTTP request is shown in the status field of the HTTP response header, which contains standard HTTP status codes:
- a 2xx code for success
- a 4xx or 5xx code for failure
The header of the response looks something like this:
HTTP/1.1 200 OK Date: Thu, 03 Mar 2018 03:39:16 PDT Content-Length: 24768 Content-Type: application/vnd.deem.openalliance.v1.3+json;charset=utf-8;version=v1.3.2 Cache-Control: no-cache, no-store, must-revalidate Pragma: no-cache Expires: 0 Connection: close Server: Deem/1.1
HTTP Headers (Response)
The following list of HTTP request and response headers represents a subset of the headers a Deem API client can expect to receive. The set of headers listed here comprises all headers that influence RESTful semantics.
Header | Description | Example |
---|---|---|
| The content type of response, matches the request's path version & |
|
| Absolute URL of new resource location, used in | |
| Optional, can be included only after a |
HTTP Response Codes
The following HTTP response codes can be expected.
Success
HTTP Status Code | Deem Error Code | Reason | Response Body |
---|---|---|---|
200 | OK | The RESTful action (any method) completed without error | Response object (depends on domain, resource, action, and version) |
Redirect
HTTP Status Code | Deem Error Code | Reason | Response Body |
---|---|---|---|
301 | Moved Permanently | The resource has moved to a new home; the URI has changed. See Redirection and URI changes | - |
Error Codes
HTTP Status Code | Deem Error Code | Reason | Response Body |
---|---|---|---|
400 | BadRequest.PageSize.Invalid | The page size parameter could not be understood (potential causes could be a non-numeric, non-integer or, negative value, page size higher than the maximum pages) | Code and Message with more information |
400 | BadRequest.StartIndex.Invalid | The start index parameter could not be understood (potential causes could be a non-numeric, non-integer or, negative value, page size higher than the maximum pages) | Code and Message with more information |
400 | BadRequest.StartTime.Invalid | The start time parameter was either missing or could not be understood, potentially because it was not formatted correctly | Code and Message with more information |
400 | BadRequest.EndTime.Invalid | The end time parameter was either missing or could not be understood, potentially because it was not formatted correctly, or if it was before the start time. | Code and Message with more information |
401 | Unauthenticated.Credentials.Invalid* | Invalid credentials supplied | No body, not too much detail here |
403 | Forbidden.Tenant.Site* | The credentials are correct but the tenant does not have access to the site. | No body, not too much detail here |
404 | Not.Found.{ResourceType}* | No resouce found with the requested URI. May optionally provide the resource type. | No body, not too much detail here |
405 | Method.Not.Allowed | The resource does not support the given method | Allow header should be used to indicate supported methods |
406 | Not.Acceptable.Version | The server received request with an empty or invalid | Response detailing oldest and latest supported versions or supported representation formats |
429 | Too.Many.Requests | The maximum number of allowed requests is reached in a given amount of time ("rate limiiting"). | Response detailing the maximum number of requests allowed in a given time |
500 | Internal.Server.Error | An error occured on the server | - |
503 | Service.Unavailable | The service is overloaded, server can specify Retry-After response header to throttle traffic | - |
* 401 vs 403: 401 Indicates that authentication failed/is required while 403 usually means authentication was successful but the user is not authorized to access resource.
Deem Response Body
The response body, in JSON format (unless specified otherwise for a particular resource), immediately follows the header.
The root of the JSON object in the response for all Booking Retrieve endpoints is either a single trip
or a collection trips
. Detailed structure and format in the Response Schema section.
Response Objects
For most API resources, the response objects are either a single itinerary or a list of itineraries. Itineraries are called Trips; more details in the Deem Object Model section.
For some API resources, as in the receipts API, the response body is a pdf file.
Deem Object Model
Expense-centric Object Model
Deem Alliance's responses are structured with an Expense Management Company (EMC) in mind. At the core of a response is a Trip or a list of Trips. A trip comprises of Transactions, where each Transaction would correspond to a real financial transaction (e.g., a credit card transaction). Transactions can always be grouped together in a Trip.
Transactions can be of several types, corresponding to a travel segment or a fee. Typically, each traveler in a booking has their own transaction. However, there is a single user booking a trip. The following sections describe fields in each object
Trip
Trip is the root of all objects in the response data, and corresponds to a booking made on the Deem Travel site.
Field | Description | Type | Optional |
---|---|---|---|
tripUuid | The unique identifier for each trip | String | No |
revision | The revision number of the trip | Numeric | No |
tripName | Name of the trip as entered by the user | String | Yes |
user | The USER object who made the booking | User | No |
bookingStatus | Booking Status of the trip | String, one from the enumeration CONFIRMED | No |
agencyName | The Travel Agency used for the trip | String | Yes |
tripCreationTime | Time the trip was first created | Datetime | No |
tripLastModificationTime | Time the trip was last modified | Datetime | No |
transactions | An array of transactions in the trip | Array of Transaction | No |
Transaction
A trip comprises of Transactions, where each Transaction would correspond to a real financial transaction (e.g., a credit card transaction). Transactions can always be grouped together in a Trip.
A Transaction can be of one or more different types
Field | Description | Type | Optional |
---|---|---|---|
transactionUuid | The unique identifier of the transaction | String | No |
tripUuid | The unique identifier of the trip this transaction belongs to | String | No |
revision | Revision number for this transaction | Integer | No |
transactionDate | The date the transaction occured | Datetime | No |
traveler | The traveler traveling on this booking | Traveler | No |
prepaidAmount | Amount of the booking, if prepaid | Numeric (2 decimals) | No |
payableLaterAmount | Amount of the booking, if payable later | Numeric (2 decimals) | No |
taxes | Total taxes (already included in the amounts above) | Numeric (2 decimals) | No |
currencyCode | The 3-letter code for currency in which the amount was charged | String | No |
bookingStatus | Status of the booking of this segment. | String, one from the enumeration CONFIRMED | No |
inPolicy | Whether this transaction was booked in-policy | Boolean | No |
policyViolationReason | Reason what caused the policy violation | String | Yes |
policyViolationJustification | Justification provided by end user for violating the policy | String | Yes |
type | Type of transaction | String, one from the enumeration HOTEL, | No |
confirmationNumber | Reservation number, etc | String | Yes |
ticketNumber | Ticket number if a ticket is issued | String | Yes |
ticketIssueDate | Date of issue of tickets | Datetime | Yes |
vendorCode | The code of the vendor that billed for this transaction | String | Yes |
vendorName | The vendor that blled for this transaction | String | Yes |
vendorPhone | The phone number of the vendor | String | Yes |
paymentType | The type of the card used for the booking | String, one from the enumeration: CREDIT_CARD, | Yes |
paymentLabel | The label of the card used for booking, may include last four digits | String | Yes |
transactionDetails | Details about a transaction, can be one type of transaction. The object will depend on the type of transaction | One of: | No |
Flight
A transaction detail object representing a flight segment.
Field | Description | Type | Optional |
---|---|---|---|
originAirportCode | The origin airport code | String | No |
originAirportLocation | The full location of the origin airport | Location | Yes |
destinationAirportCode | The destination airport code | String | No |
destinationAirportLocation | The full location of the destination airport | Location | Yes |
departureTime | The date and time of departure from the origin airport | Datetime | No |
arrivalTime | The date and time of arrival at the destination airport | Datetime | No |
serviceClass | The class of service | String, one from the enumeration: COACH, | No |
bookingCode | The booking code | String | Yes |
carrierCode | Carrier Code | String | No |
carrierName | Carrier Name | String | No |
flightNumber | Flight Number | String | No |
legSequence | Sequence of the flight leg | Integer | No |
segmentSequence | Sequence of the flight segment | Integer | No |
Hotel
A transaction detail object representing a hotel reservation.
Field | Description | Type | Optional |
---|---|---|---|
checkinDate | The check in at the hotel | Datetime | No |
checkoutDate | The check out date at the hotel | Datetime | No |
hotelName | The name of the hotel. This can be different than the chain. | String | No |
hotelChainCode | The chain code for the chain the hotel belongs to | String | Yes |
starRating | Number of stars the hotel has, if any | Integer | Yes |
location | The location details, address and phone number, of the hotel | Location | Yes |
numberOfGuests | The number of guests booked for the rooom | Integer | No |
breakfastIncluded | Whether breakfast is included as part of the tariff | Boolean | Yes |
averageRate | The average rate for the stay | Numeric (2 decimal places) | No |
currency | The 3-letter currency code for the rate | String | No |
roomType | Type of the room booked | String | Yes |
roomDescription | Specific details about the room | String | Yes |
CarRental
A transaction detail object representing a Car Rental reservation.
Field | Description | Type | Optional |
---|---|---|---|
pickupLocation | The location where the traveler needs to be picked up | Location | Yes |
dropoffLocation | The location where the traveler needs to be dropped at | Location | Yes |
pickupAirportCode | If the pickup location is an airport, the airport code | String | Yes |
dropoffAirportCode | If the dropoff location is an airport, the airport code | String | Yes |
pickupTime | The date and time of pickup | Datetime | No |
dropoffTime | The date and time of dropoff | Datetime | No |
carType | The type of the car | String, some examples include: CONVERTIBLE, | Yes |
carClass | The car class | String, one from the enumeration: MINI, | Yes |
unlimitedMileage | Whether the renal allows for unlimited mileage | Boolean | No |
carTransmission | Automatic or Manual | String, one from the enumeration: MANUAL, | Yes |
averageRate | The average rate for the rental | Numeric (2 decimal places) | Yes |
currency | The 3-letter currency code for the rate | String | Yes |
rateType | The rate type, e.g., Daily,Weekly, Monthly | String, one from the enumeration DAILY, | Yes |
CarService
A transaction detail object representing a Car Service booking.
Field | Description | Type | Optional |
---|---|---|---|
pickupLocation | The location where the traveler needs to be picked up | Location | No |
dropoffLocation | The location where the traveler needs to be dropped at | Location | No |
pickupTime | The date and time of pickup | Datetime | No |
dropoffTime | The date and time of dropoff | Datetime | Yes |
carType | The type of the car | StringString, some examples include: CONVERTIBLE, | Yes |
carClass | The car class | String, one from the enumeration: MINI, | Yes |
Train
A transaction detail object representing a Train booking.
Field | Description | Type | Optional |
---|---|---|---|
originStationCode | The origin station code | String | No |
originStationLocation | The full location of the origin station | Location | Yes |
destinationStationCode | The destination station code | Datetime | No |
destinationStationLocation | The full location of the destination station | Location | Yes |
departureTime | The time of departure from the origin station | Datetime | No |
arrivalTime | The time of arrival at the destination station | Datetime | No |
serviceClass | The class of service | String | No |
carrierCode | Carrier Code | String | Yes |
carrierName | Carrier Name | String | No |
trainNumber | Train Number | String | No |
legSequence | Sequence of the flight leg | Integer | No |
segmentSequence | Sequence of the flight segment | Integer | No |
Fees
A transaction detail object representing a Fees transaction.
Field | Description | Type | Optional |
---|---|---|---|
type | The type of the fees | String | No |
User
Representation of the User object as used in the Trip object. The user books the trip on their Deem Travel account
Field | Description | Type | Optional |
---|---|---|---|
userId | Unique user identifier | String | No |
siteId | Unique site identifier | String | No |
siteName | Name of the site | String | No |
Traveler
Representation of the Traveler object as used in the Transaction object.
Field | Description | Type | Optional |
---|---|---|---|
title | Title | String | Yes |
firstName | First name or Given name of the Traveler | String | No |
middleInitial | Middle name initial | String | Yes |
lastName | Last name or surname of the Traveler | String | No |
Email id used to receive emails about the booking | String | No | |
primary | Whether the traveler is the primary traveler on the booking | Boolean | Yes |
phoneNumbers | Comma-separated list of phone numbers for the traveler | String | Yes |
Location
Representation of the Location object.
Field | Description | Type | Optional |
---|---|---|---|
locationCode | Location code, if any | String | Yes |
locationName | A name of the location, if any | String | Yes |
street1 | Street Address Line 1 | String | No |
street2 | Street Address Line 1 | String | Yes |
cityCode | City code, if any | String | Yes |
cityName | City Name | String | No |
stateCode | State Code | String | Yes |
stateName | State full name | String | Yes |
countryCode | Country code, if any | String | Yes |
countryName | Country Name | String | Yes |
postalCode | ZIP or PIN code or postal code | String | Yes |
Sample Objects
Here are a few examples of different types of objects based on how bookings are made:
Example 1. Flight
Here is a sample flight booking, which also comes with an agency fees:
{ 'tripUuid': 'cb5438ad-c573-4d86-99ff-7f5a5d9bdd02', 'revision': 1, 'tripName': 'Oregon - FH', 'user': { 'externalUserId': 'batman', 'externalSiteId': 'wayne', 'siteName': 'Wayne Enterprises' }, 'tripCreationTime': '2017-11-14T11:14:59', 'agencyName': 'The Enigma', 'transactions': [{ 'transactionUuid': '3b63190c-20ae-489e-ba1f-dc2c78ecc190', 'tripUuid': 'cb5438ad-c573-4d86-99ff-7f5a5d9bdd02', 'version': 1, 'transactionDate': '2017-11-14T00:00', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': 496.39, 'payableLaterAmount': 0, 'taxes': 67.45, 'fees': 0, 'taxesAndFees': 0, 'currency': 'USD', 'bookingStatus': 'CONFIRMED', 'inPolicy': false, 'policyViolationReason': '', 'policyViolationJustification': 'No parking for Batmobile', 'confirmationNumber': 'RFRMJO', 'ticketNumber': '0277015599008', 'ticketIssueTime': '2017-11-14T00:00', 'vendorCode': 'AS', 'vendorName': 'Alaska Airlines', 'paymentType': 'UNKNOWN', 'paymentLabel': '', 'type': 'FLIGHT', 'segments': [{ 'originAirportCode': 'PDX', 'originAirportLocation': { 'locationCode': 'PDX', 'locationName': 'Portland International Airport', 'street1': null, 'street2': null, 'cityCode': 'PDX', 'cityName': 'Portland', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'destinationAirportCode': 'RDM', 'destinationAirportLocation': { 'locationCode': 'RDM', 'locationName': 'Roberts Field', 'street1': null, 'street2': null, 'cityCode': 'RDM', 'cityName': 'Redmond', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'departureTime': '2017-12-25T11:50', 'arrivalTime': '2017-12-25T12:29', 'serviceClass': 'COACH', 'bookingCode': 'Y', 'carrierCode': 'AS', 'carrierName': 'Alaska Airlines', 'flightNumber': '2325', 'legSequence': 1, 'segmentSequence': 1 }, { 'originAirportCode': 'RDM', 'originAirportLocation': { 'locationCode': 'RDM', 'locationName': 'Roberts Field', 'street1': null, 'street2': null, 'cityCode': 'RDM', 'cityName': 'Redmond', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'destinationAirportCode': 'PDX', 'destinationAirportLocation': { 'locationCode': 'PDX', 'locationName': 'Portland International Airport', 'street1': null, 'street2': null, 'cityCode': 'PDX', 'cityName': 'Portland', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'departureTime': '2017-12-29T05:09', 'arrivalTime': '2017-12-29T05:51', 'serviceClass': 'COACH', 'bookingCode': 'Y', 'carrierCode': 'AS', 'carrierName': 'Alaska Airlines', 'flightNumber': '2058', 'legSequence': 2, 'segmentSequence': 2 }] }, { 'transacionUuid': 'e53f1ace-98f5-49bd-90d5-2a57f4a17a42', 'version': 1, 'transactionDate': '2017-11-14T00:00', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': 10.0, 'payableLaterAmount': 0, 'taxes': 0, 'fees': 0, 'taxesAndFees': 0, 'currency': 'USD', 'bookingStatus': 'CONFIRMED', 'inPolicy': false, 'policyViolationReason': null, 'policyViolationJustification': null, 'confirmationNumber': null, 'ticketNumber': null, 'ticketIssueTime': null, 'vendorCode': null, 'vendorName': 'The Enigma', 'paymentType': 'UNKNOWN', 'paymentLabel': '', 'type': 'FEES', 'segments': [{ 'type': 'AGENCY_FEES', 'vendorName': 'Globe', 'vendorPhone': '650-2112-8440', 'location': { 'locationCode': null, 'locationName': '', 'street1': '666 ', 'street2': null, 'cityCode': null, 'cityName': 'Gotham City', 'stateCode': 'WI', 'stateName': 'Wisconsin', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '53540' } }] }] }
Example 2: Hotel
This is a Hotel booking, paid upon checkout:
{ 'tripUuid': 'cb5438ad-c573-4d86-99ff-7f5a5d9bdd02', 'revision': 1, 'tripName': 'Oregon - FH', 'user': { 'externalUserId': 'batman', 'externalSiteId': 'wayne', 'siteName': 'Wayne Enterprises' }, 'tripCreationTime': '2017-11-14T11:14:59', 'agencyName': 'The Enigma', 'transactions': [{ 'transactionUuid': '0812b1ef-aed8-4eef-a29d-c7e864c9b4d7', 'revision': 1, 'transactionDate': '2018-01-20T00:00', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': 0, 'payableLaterAmount': 185.13, 'taxes': 20.13, 'fees': 0, 'taxesAndFees': 20.13, 'currency': 'USD', 'bookingStatus': 'CANCELLED', 'inPolicy': true, 'policyViolationReason': null, 'policyViolationJustification': null, 'confirmationNumber': 0, 'ticketNumber': null, 'ticketIssueTime': null, 'vendorCode': '11100', 'vendorName': 'Booking.com', 'paymentType': 'CREDIT_CARD', 'paymentLabel': '"Visa3" ************0003', 'type': 'HOTEL', 'segments': [{ 'checkinDate': '2018-01-17T14:00', 'checkoutDate': '2018-01-20T10:00', 'hotelName': 'Rainbow Motel', 'hotelChainCode': null, 'starRating': '2', 'vendorPhone': '15413821821', 'location': { 'locationCode': 'RDM', 'locationName': 'Bend', 'street1': '154 NE Franklin St', 'street2': null, 'cityCode': 'RDM', 'cityName': 'Bend', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'numberOfGuests': 1, 'breakfastIncluded': false, 'averageRate': 55.0, 'currency': 'USD', 'roomType': 'Queen', 'roomDescription': 'Queen Room Free cancellation - Free WiFi' }] }] }
Example 3: Flight, Hotel, and Car Rental
A typical full itinerary, comprising of a flight, hotel, and car rental
{ 'tripUuid': 'cb5438ad-c573-4d86-99ff-7f5a5d9bdd02', 'revision': 1, 'tripName': 'Oregon - FH', 'user': { 'externalUserId': 'batman', 'externalSiteId': 'wayne', 'siteName': 'Wayne Enterprises' }, 'tripCreationTime': '2017-11-14T11:14:59', 'agencyName': 'The Enigma', 'transactions': [{ 'transactionUuid': '3b63190c-20ae-489e-ba1f-dc2c78ecc190', 'tripUuid': 'cb5438ad-c573-4d86-99ff-7f5a5d9bdd02', 'version': 1, 'transactionDate': '2017-11-14T00:00', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': 496.39, 'payableLaterAmount': 0, 'taxes': 67.45, 'fees': 0, 'taxesAndFees': 0, 'currency': 'USD', 'bookingStatus': 'CONFIRMED', 'inPolicy': false, 'policyViolationReason': '', 'policyViolationJustification': 'No parking for Batmobile',, 'confirmationNumber': 'RFRMJO', 'ticketNumber': '0277015599008', 'ticketIssueTime': '2017-11-14T00:00', 'vendorCode': 'AS', 'vendorName': 'Alaska Airlines', 'paymentType': 'UNKNOWN', 'paymentLabel': '', 'type': 'FLIGHT', 'segments': [{ 'originAirportCode': 'PDX', 'originAirportLocation': { 'locationCode': 'PDX', 'locationName': 'Portland International Airport', 'street1': null, 'street2': null, 'cityCode': 'PDX', 'cityName': 'Portland', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'destinationAirportCode': 'RDM', 'destinationAirportLocation': { 'locationCode': 'RDM', 'locationName': 'Roberts Field', 'street1': null, 'street2': null, 'cityCode': 'RDM', 'cityName': 'Redmond', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'departureTime': '2017-12-25T11:50', 'arrivalTime': '2017-12-25T12:29', 'serviceClass': 'COACH', 'bookingCode': 'Y', 'carrierCode': 'AS', 'carrierName': 'Alaska Airlines', 'flightNumber': '2325', 'legSequence': 1, 'segmentSequence': 1 }, { 'originAirportCode': 'RDM', 'originAirportLocation': { 'locationCode': 'RDM', 'locationName': 'Roberts Field', 'street1': null, 'street2': null, 'cityCode': 'RDM', 'cityName': 'Redmond', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'destinationAirportCode': 'PDX', 'destinationAirportLocation': { 'locationCode': 'PDX', 'locationName': 'Portland International Airport', 'street1': null, 'street2': null, 'cityCode': 'PDX', 'cityName': 'Portland', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'departureTime': '2017-12-29T05:09', 'arrivalTime': '2017-12-29T05:51', 'serviceClass': 'COACH', 'bookingCode': 'Y', 'carrierCode': 'AS', 'carrierName': 'Alaska Airlines', 'flightNumber': '2058', 'legSequence': 2, 'segmentSequence': 2 }] }, { 'transacionUuid': 'e53f1ace-98f5-49bd-90d5-2a57f4a17a42', 'version': 1, 'transactionDate': '2017-11-14T00:00', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': 10.0, 'payableLaterAmount': 0, 'taxes': 0, 'fees': 0, 'taxesAndFees': 0, 'currency': 'USD', 'bookingStatus': 'CONFIRMED', 'inPolicy': false, 'policyViolationReason': null, 'policyViolationJustification': null, 'confirmationNumber': null, 'ticketNumber': null, 'ticketIssueTime': null, 'vendorCode': null, 'vendorName': 'The Enigma', 'paymentType': 'UNKNOWN', 'paymentLabel': '', 'type': 'FEES', 'segments': [{ 'type': 'AGENCY_FEES', 'vendorName': 'The Enigma', 'vendorPhone': '650-2112-8440', 'location': { 'locationCode': null, 'locationName': '', 'street1': '666 ', 'street2': null, 'cityCode': null, 'cityName': 'Gotham City', 'stateCode': 'WI', 'stateName': 'Wisconsin', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '53540' } }] }, { 'transactionUuid': '0812b1ef-aed8-4eef-a29d-c7e864c9b4d7', 'revision': 1, 'transactionDate': '2018-01-20T00:00', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': 0, 'payableLaterAmount': 185.13, 'taxes': 20.13, 'fees': 0, 'taxesAndFees': 20.13, 'currency': 'USD', 'bookingStatus': 'CANCELLED', 'inPolicy': true, 'policyViolationReason': null, 'policyViolationJustification': null, 'confirmationNumber': 0, 'ticketNumber': null, 'ticketIssueTime': null, 'vendorCode': '11100', 'vendorName': 'Booking.com', 'paymentType': 'CREDIT_CARD', 'paymentLabel': '"Visa3" ************0003', 'type': 'HOTEL', 'segments': [{ 'checkinDate': '2018-01-17T14:00', 'checkoutDate': '2018-01-20T10:00', 'hotelName': 'Rainbow Motel', 'hotelChainCode': null, 'starRating': 2, 'vendorPhone': '15413821821', 'location': { 'locationCode': 'RDM', 'locationName': 'Bend', 'street1': '154 NE Franklin St', 'street2': null, 'cityCode': 'RDM', 'cityName': 'Bend', 'stateCode': 'OR', 'stateName': 'Oregon', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': null }, 'numberOfGuests': 1, 'breakfastIncluded': false, 'averageRate': 55.0, 'currency': 'USD', 'roomType': 'Queen', 'roomDescription': 'Queen Room Free cancellation - Free WiFi' }] }] }
Example 4: Train and Car Service
A booking where the traveler takes a train, and then arranges a Limo Service to pick them up at the train station.
{ 'tripUuid': 'cb5438ad-c573-4d86-99ff-7f5a5d9bdd02', 'revision': '1', 'tripName': 'Oregon - FH', 'user': { 'externalUserId': 'batman', 'externalSiteId': 'wayne', 'siteName': 'Wayne Enterprises' }, 'tripCreationTime': '2017-11-14T11:14:59', 'agencyName': 'The Enigma', 'transactions': [{ 'transactionUuid': '7f5a5d9bdd02-c573-4d86-99ff-cb5438ad', 'revision': '1', 'transactionDate': '2017-12-15T14:56:09', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': '176.0', 'payableLaterAmount': '0', 'taxes': '0.0', 'fees': '0.0', 'taxesAndFees': '0.0', 'currency': 'USD', 'bookingStatus': 'COMPLETED', 'inPolicy': false, 'policyViolationReason': null, 'policyViolationJustification': null, 'confirmationNumber': '9713C1', 'ticketNumber': null, 'ticketIssueTime': null, 'vendorCode': null, 'vendorName': null, 'paymentType': 'CREDIT_CARD', 'paymentLabel': '"Visa3" ************0003', 'parentTransaction': null, 'type': 'TRAIN', 'segments': [{ 'departureTime': '2018-02-07T21:39', 'arrivalTime': '2018-02-08T19:51', 'originStationCode': 'USOKJ', 'originStationLocation': { 'locationCode': 'USOKJ', 'locationName': 'Jack London Square', 'street1': null, 'street2': null, 'cityCode': null, 'cityName': 'Oakland' 'stateCode': 'CA', 'stateName': 'California', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '94607' }, 'destinationStationCode': 'USSEA', 'destinationStationLocation': { 'locationCode': 'USSEA', 'locationName': 'King Street Station', 'street1': null, 'street2': null, 'cityCode': 'USSEA', 'cityName': 'San Francisco' 'stateCode': 'CA', 'stateName': 'California', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '94107' }, 'legSequence': '1', 'segmentSequence': '1', 'serviceClass': 'COACH', 'carrierCode': '2V', 'carrierName': 'Amtrak', 'trainNumber': '14' }, { 'departureTime': '2018-02-13T09:50', 'arrivalTime': '2018-02-14T08:35', 'originStationCode': 'USSEA', 'originStationLocation': { 'locationCode': 'USSEA', 'locationName': 'King Street Station', 'street1': null, 'street2': null, 'cityCode': 'USSEA', 'cityName': 'San Francisco' 'stateCode': 'CA', 'stateName': 'California', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '94107' }, 'destinationStationCode': 'USOKJ', 'destinationStationLocation': { 'locationCode': 'USOKJ', 'locationName': 'Jack London Square', 'street1': null, 'street2': null, 'cityCode': null, 'cityName': 'Oakland' 'stateCode': 'CA', 'stateName': 'California', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '94607' }, 'legSequence': '2', 'segmentSequence': '2', 'serviceClass': 'COACH', 'carrierCode': '2V', 'carrierName': 'Amtrak', 'trainNumber': '11' }] }, { 'transactionUuid': '7f5a5d9b302-c573-4d86-99ff-cb5gf8ad', 'revision': '1', 'transactionDate': '2018-01-25T14:16', 'traveler': { 'title': 'Mr', 'firstName': 'Bruce', 'middleInitial': 'Batman', 'lastName': 'Wayne', 'email': 'batman@deem.com', 'primary': true, 'phoneNumbers': '235-6723-567' }, 'prepaidAmount': '0', 'payableLaterAmount': '59.95', 'taxes': '2.7', 'fees': '0', 'taxesAndFees': '2.7', 'currency': 'USD', 'bookingStatus': 'CONFIRMED', 'inPolicy': true, 'policyViolationReason': null, 'policyViolationJustification': null, 'confirmationNumber': '5269379A', 'ticketNumber': null, 'ticketIssueTime': null, 'vendorCode': 'KLV', 'vendorName': 'Kings Livery', 'paymentType': 'UNKNOWN', 'paymentLabel': '', 'parentTransaction': null, 'type': 'CAR_SERVICE', 'segments': [{ 'pickupLocation': { 'locationCode': 'USOKJ', 'locationName': 'Jack London Square', 'street1': null, 'street2': null, 'cityCode': null, 'cityName': 'Oakland' 'stateCode': 'CA', 'stateName': 'California', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '94607' }, 'dropoffLocation': { 'locationCode': '', 'locationName': '301 Howard Street', 'street1': '301 Howard Street', 'street2': null, 'cityCode': '', 'cityName': 'San Francisco', 'stateCode': 'CA', 'stateName': 'California', 'countryCode': 'US', 'countryName': 'United States', 'postalCode': '94107' }, 'pickupTime': '2018-01-25T14:00', 'dropoffTime': '2018-01-25T14:16', 'vendorCode': 'KLV', 'vendorName': 'Kings Livery', 'vendorPhone': '800-555-1212', 'carServiceType': 'CAR_SERVICE', 'carType': 'SEDAN', 'carClass': 'LUXURY' }] }] }
REST Resources
This section lists all the resources that be accessed, all using the Http GET method, returning a single Trip or a collection of Trips. All the Resource URIs below are relative to https://api.deem.com/alliance, which points to the latest version of the API. More on API versioning below.
All REST resources are site-scoped. A site is a company set up in Deem that represents a customer or a subsidiary. If you are an Open Alliance Partner with multiple customers using the alliance, data from different customers cannot be retrieved in a single API call.
Get Trips for Site
The API resource that returns all Travel booking data across all users under a given site. Depending on the number of users making Travel bookings, this can get potentially large, even with pagination. Therefore, this always needs to be augmented with a time interval for which the data is requested.
Request
Method | Resource | Action |
---|---|---|
GET |
| Get all trips for all users for a specific site |
Path Parameters
Parameter | Description | Required |
---|---|---|
| The version of the API | Yes |
| External identifier of the user's site | Yes |
Query Parameters
Parameter | Description | Format | Required? | Default |
---|---|---|---|---|
| Starting time from which trips booked or modified will be returned | ISO 8601 | Yes | N/A |
| End time till which trips booked or modified will be returned | ISO 8601 | No | Current time |
| Starting time from which trips booked or modified will be returned | Integer | No | 0 |
| End time till which trips booked or modified will be returned | Integer | No | 20 |
Headers
Header | Header type | Description | Format/Validation | Required |
---|---|---|---|---|
x-deem-tenant-id | Authentication | ID of the Open Alliance partner/tenant | Valid tenant id received from Deem | Yes |
Accept | Response type | Media type(s) acceptable for the response. |
| Yes |
Sample request
curl -H "x-deem-tenant-id: acmepartner" \ -H "Accept: application/vnd.deem.openalliance+json" \ "https://api.deem.com/alliance/v1.3/site/wayne/trip/"
Get Trips for User
The API resource that returns all bookings owned by a given user under a given site. Even though this is a single user in a site, the response can get potentially large over a large period of time. Therefore, this always needs to be augmented with a time interval for which the data is requested.
Request
Method | Resource | Action |
---|---|---|
GET |
| Get transactions for a specific user within a site |
Path Parameters
Parameter | Description | Required |
---|---|---|
| The version of the API | Yes |
| External identifier of the user's site/company | Yes |
| External identifier of the user | Yes |
Query Parameters
Parameter | Description | Format | Required? | Default |
---|---|---|---|---|
| Starting time from which trips booked or modified will be returned | ISO 8601 | Yes | N/A |
| End time till which trips booked or modified will be returned | ISO 8601 | No | Current time |
| Starting time from which trips booked or modified will be returned | Integer | No | 0 |
| End time till which trips booked or modified will be returned | Integer | No | 20 |
Headers
Header | Header type | Description | Format/Validation | Required |
---|---|---|---|---|
x-deem-tenant-id | Authentication | ID of the Open Alliance partner/tenant | Valid tenant id received from Deem | Yes |
Accept | Response type | Media type(s) acceptable for the response. |
| Yes |
Sample request
curl -H "x-deem-tenant-id: acmepartners" \ -H "Accept: application/vnd.deem.openalliance+json" \ “https://api.deem.com/alliance/v1.3/site/wayne/user/batman/trip/
Get Trip by ID
The Get Trip API returns an exact trip owned by a user within a site. The user-site combination should be the correct one owning the trip. A requested trip id not owned by the passed in user or site will return a 400.
This can be also used to get all the revisions of a booking, unlike the othe collection APIs above that only result in the latest version of the booking. This can be achieved by sending true
into the all_revisions
query parameter, which is optional and defaulted to false if not present.
Request
Method | Resource | Action |
---|---|---|
GET | /version/{version_number}/site/{site_id}/user/{user_id}/trip/{trip_uuid} | Get the full itinerary for the give trip UUID |
Path Parameters
Parameter | Description | Required |
---|---|---|
| The version of the API | Yes |
| External identifier of the user's site/company | Yes |
| External identifier of the user | Yes |
| The identifier for the trip. Passed in previously with the list of trips for a user. | Yes |
Query Parameters
Parameter | Description | Format | Required? | Default |
---|---|---|---|---|
| Flag indiicating if all revisions of a trip are desired or just the latest one | boolean | No | false |
Headers
Header | Header type | Description | Format/Validation | Required |
---|---|---|---|---|
x-deem-tenant-id | Authentication | ID of the Open Alliance partner/tenant | Valid tenant id received from Deem | Yes |
Accept | Response type | Media type(s) acceptable for the response. |
| Yes |
Sample request
curl -H "x-deem-tenant-id: acmepartners" \ -H "Accept: application/vnd.deem.openalliance+json" \ “https://api.deem.com/alliance/v1.3/site/wayne/user/batman/trip/d45efe38-a719-40ad-bd54-67e67c1b3e21/"
Get Receipt for Trip
The Get Travel Receipt API returns a receipt (a PDF version of the Trip Confirmation page) for a given trip. The trip id is a UUID, and directly corresponds to a process id.
Request
Method | Resource | Action |
---|---|---|
GET | /{version_number}/site/{site_id}/user/{user_id}/trip/{trip_UUID}/receipt | Get a Deem receipt for the given trip |
Path Parameters
Parameter | Description | Required |
---|---|---|
| The version of the API | Yes |
| External identifier of the user's site/company | Yes |
| External identifier of the user | Yes |
| The identifier for the trip. Passed in previously with the list of trips for a user. | Yes |
Headers
Header | Header type | Description | Format/Validation | Required |
---|---|---|---|---|
x-deem-tenant-id | Authentication | ID of the Open Alliance partner/tenant | Valid tenant id received from Deem | Yes |
Accept | Response type | Media type(s) acceptable for the response. |
| Yes |
Sample request
curl -H "x-deem-tenant-id: acmepartners" \ -H "Accept: application/vnd.deem.openalliance+json" \ “https://api.deem.com/alliance/v1.3/site/wayne/user/robin/trip/d45efe38-a719-40ad-bd54-67e67c1b3e21/receipt/"
Response
Sample Response
HTTP/1.1 200, OK Content-Type: application/pdf The pdf binary file.
Get Version
The Get Version API returns the latest version of the API. Alternatively, it can also be used to find details about a specific version, including changelogs.
Request
Method | Resource | Action |
---|---|---|
GET | /{version_number}/version | Get details about a specific version |
Path Parameters
Parameter | Description | Required |
---|
Headers
Header | Header type | Description | Format/Validation | Required |
---|---|---|---|---|
x-deem-tenant-id | Authentication | ID of the Open Alliance partner/tenant | Valid tenant id received from Deem | Yes |
Accept | Response type | Media type(s) acceptable for the response. |
| Yes |
Sample request
curl -H "x-deem-tenant-id: acmepartners" \ -H "Accept: application/vnd.deem.openalliance+json" \ “https://api.deem.com/alliance/v1.3/version/"
Response
Sample Response
HTTP/1.1 200, OK { version: 1.3.2 fieldsAdded: { hotelPhoneNumber, carRentalProvider } }
Healthcheck
The health check endpoint can be used to check if the API is up and running. This returns a 200 OK without a response body. This does not mandatorily need a version. The version is actually ignored if passed.
Request
Method | Resource | Action |
---|---|---|
GET | /health | Check the health of the Deem Open API |
Headers
Header | Header type | Description | Format/Validation | Required |
---|---|---|---|---|
x-deem-tenant-id | Authentication | ID of the Open Alliance partner/tenant | Valid tenant id received from Deem | Yes |
Accept | Response type | Media type(s) acceptable for the response. |
| No |
Sample request
curl -H "x-deem-tenant-id: acmepartners" \ -H "Accept: application/vnd.deem.openalliance+json" \ “https://api.deem.com/alliance/health/"
Response
Sample Response
HTTP/1.1 200, OK