Field Descriptions

Note: This page has not yet been converted to the new developer portal format. Please use Swagger to test this API.

Data Models

Field Descriptions

Name	Type	Value	Description	Validation	Validation Message
externalItineraryId	String	e.g. 134808153	The external id of the itinerary set by the client.	Not Required. Max length is 100 characters.	Field ['externalItineraryId'] length is 164, exceeds the limit of 100 characters
pnr	String	e.g. DWKURT	(Passenger Name Record): the unique identifier of one (or many) passenger’s itineraries. Record Locator of the PNR.	Required. Max length is 100 characters.	◊ Field ["pnr"] is empty. ◊ Field ['pnr'] length is 164, exceeds the limit of 100 characters
itineraryStatus	String	◊ Canceled ◊ Custom Status(e.g. Active) ◊ etc.	The status of the itinerary. The Canceled Status of the itinerary in our platform means we will not generate segments(itineraries) and expected locations for the itinerary or remove the existing itinerary and expected locations with the same pnr or planId.	Required. Max length is 30 characters.	◊ Field ["itineraryStatus"] is empty. ◊ Field ['itineraryStatus'] length is 64, exceeds the limit of 30 characters
itinerarySource	String		The source of the itinerary.	Not Required. Max length is 30 characters.	◊ Field ['itinerarySource'] length is 64, exceeds the limit of 30 characters
createdDate	String	2020-11-22 T08:45:00Z	The date that the itinerary was created, in UTC, ISO date format.	Not Required.	◊ Field ['createdDate'] value 2017-05-22T08:45:00 is invalid!
lastModifiedDate	String	2020-11-30 T08:45:00Z	The date that the itinerary was last modified, in UTC, ISO date format.	Not Required.	◊ Field ['lastModifiedDate'] value 2017-07-22T08:45:00 is invalid!
extendedInfo	Object		Extended information at the itinerary level. All fields inside the object are optional as extra information for the system. It does not impact the existing ones.	Not Required.
segments	Array		List of segments in this itinerary.	Required for the itinerary without "Canceled" status. ◊ If all segments of the itinerary are invalid, the API request will be rejected. ◊ If only some of the segments are invalid, the API request will still be successful but the system only generates expected locations based on the valid segments data.	◊ The itinerary does not contain any segments ◊ All segments of the itinerary are invalid, PNR creation failed
passengers	Array		List of passengers in this itinerary.	Required for the itinerary without "Canceled" status. The system will verify if there is a contact matching with the provided passengers.	◊ Field [‘passengers’] is empty! ◊ Travel matching error, no contact matching.
travelArranger	Object		The travel arranger for this itinerary.	Not Required.

Itinerary ExtendedInfo

Field Name	Data Type	Values	Description	Validation
startDate	String	2021-11-22 T08:45:00Z	Itinerary start date, in UTC, ISO date format.	Not Required.
endDate	String	2021-11-22 T08:45:00Z	Itinerary end date, in UTC, ISO date format.	Not Required.
diType	String	◊ D ◊ I	Domestic/International type of the itinerary, which should be calculated based on the number of the itinerary segment countries. If there are multiple countries within the trip, it is International (I), otherwise Domestic (D).	Not Required.
bookedBy	String	e.g. Jim Green	The person who booked the itinerary.	Not Required.
isTicketed	Boolean	◊ true ◊ false ◊ null	Flag indicating whether the itinerary is already ticketed, or null for unknown.	Not Required.
reasonDesc	String	e.g. Business Travel	Travel reason description.	Not Required.
approver	String	e.g. Alice Brown	Approver of the travel.	Not Required.
costCenter	String	e.g. A123	Cost center for the travel.	Not Required.
travelAuthCode	String	e.g. ABCD123456	Travel authorization code.	Not Required.
emailAddresses	Array	e.g. ["[email protected]", "[email protected]"]	Email address list associated with itinerary.	Not Required.
travelAgencyInfo	Object		Travel agency info.	Not Required.

TravelAgencyInfoTest

Field Name	Data Type	Values	Description	Validation
externalAgencyId	Integer	e.g. 123	The external id of the travel agency, for tracking purposes.	Not Required.
agencyName	String	e.g. Universal Travel Agency	Agency name.	Not Required.
agencyContact	String	e.g. Tom Miller	Agency contact person name.	Not Required.
agencyEmail	String	e.g. [email protected]	Agency contact email.	Not Required.
agencyTel1	String	e.g. +13317987654	Agency telephone number 1.	Not Required.
agencyTel2	String	e.g. +13317987655	Agency telephone number 2.	Not Required.
gdsName	String	e.g. Sabre	GDS name.	Not Required.

Segments

Name	Type	Value	Description	Validation	Validation Message
type	String	e.g. Air	The type of segment.	Required and should be any value listed here: ◊ Car ◊ Hotel ◊ Rail ◊ Air	◊ Field ['segments.type'] is empty! ◊ Field ['segments.type'] value Mobile is invalid!
supplierCode	String	e.g. SQ	The code of the vendor.	Not Required. Max length is 256 characters.	◊ "Field ['segments.supplierCode'] length is 300, exceeds the limit of 256 characters"
supplierName	String	e.g. Singapore Airlines	The name of the vendor like the Airline, Railway, Hotel, or Car Renting Company Name.	Not Required. Max length 1024 characters.	◊ "Field ['segments.supplierName'] length is 1500, exceeds the limit of 1024 characters"
airRailNumber	String	e.g. 301	Flight Or Rail Number.	Required for the segment of Air/Rail type. The value must not be blank or all zeros.	"Field ['segments.airRailNumber'] value 00000 is invalid"
fromIataCode	String	e.g. DFW	Three-letter code of the departure IATA location. Our platform can get the location name, country, city, state, time zone, latitude, longitude by this IATA code.	For Air/Rail, it's recommended to provide it. Refer to more details in "Address And Timezone Adoption Rule"
toIataCode	String	e.g. IAD	Three-letter code of the destination IATA location. Our platform can get the location name, country, city, state, time zone, latitude, longitude by this IATA code.	For Air/Rail, it's recommended to provide it. Refer to more details "Address And Timezone Adoption Rule"
fromDateTime	String	2020-12-03 T10:15:30Z	The starting date-time for this segment, in UTC. ISO Date Format: YYYY-MM-DDThh:mm:ssZ.	See "Date Time Adoption Rule"	◊ Field ['segments.fromDateTime'] and ['segments.fromDateTimeLocal'] is empty ◊ Field ['segments.fromDateTime'] value 2018-07-21T00:00:00 is invalid ◊ "Field ['segments.fromDateTime'] and Field ['segments.fromTimeZone'] is empty"
toDateTime	String	2020-12-03 T10:15:30Z	The ending date-time for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ssZ.	See "Date Time Adoption Rule"	◊ Field ['segments.toDateTime'] and ['segments.toDateTimeLocal'] is empty ◊ Field ['segments.toDateTime'] value 2018-07-31T00:00:00 is invalid ◊ "Field ['segments.fromDateTime'] and Field ['segments.fromTimeZone'] is empty"
fromDateTime Local	String	2020-12-03 T02:15:30	The starting date-time for this segment in the departure location's time zone. Format: YYYY-MM-DDThh:mm:ss	See "Date Time Adoption Rule"	◊ Field ['segments.fromDateTime'] and ['segments.fromDateTimeLocal'] are empty ◊ Field ['segments.fromDateTimeLocal'] value 2017/07/21T16:50:00 is invalid
toDateTime Local	String	2020-12-03 T02:15:30	The starting date-time for this segment in the destination location's time zone. Format: YYYY-MM-DDThh:mm:ss	See "Date Time Adoption Rule"	◊ Field ['segments.toDateTime'] and ['segments.toDateTimeLocal'] are empty ◊ Field ['segments.toDateTimeLocal'] value 2017/07/21T16:50:00 is invalid
fromTimeZone	String	e.g. Asia /Shanghai EST	The time zone for this segment in the departure location. The TZ database name is supported.	The time zone is required when there is a local date time string (fromDateTimeLocal) but no UTC date time (fromDateTime), or IATA location's (fromIataCode).	◊ Field ['segments.fromTimeZone'] is empty! ◊ Field [‘segments.fromTimeZone’] value Asia/Chongqing111 is invalid!
toTimeZone	String	e.g. Asia/ Shanghai EST	The time zone for this segment in the destination location. The TZ database name is supported.	The time zone is required when there is a local date time string (toDateTimeLocal) but no UTC date time (toDateTime), or IATA location's (toIataCode).	◊ Field ['segments.toTimeZone'] is empty! ◊ Field [‘segments.toTimeZone’] value Asia/Chongqing111 is invalid!
extendedInfo	Object		Extended information at the segment level. All fields inside the object are optional, as extra information for the system. It does not impact the existing ones.	Not required.
fromAddress	Object		The address info for this segment in the departure location.	See "Address And Timezone Adoption Rule"
toAddress	Object		The address info for this segment in the destination location.	See "Address And Timezone Adoption Rule"

Segment ExtendedInfo

Field Name	Data Type	Values	Description	Validation
externalSegmentId	Integer	e.g. 232028393	The external id of the segment for tracking purposes.	Not Required.
externalSegmentIndex	Integer	e.g. 1	The sequence of the current segment in all same type segments of the itinerary, based on time ASC. The earliest segment would have the smallest index.	Not Required.
carHotelExtraInfo	Object	Only available for the segment with type Car or Hotel.	Not Required.	Not Required.

CarHotelExtraInfo

Field Name	Data Type	Values	Description	Validation
telephoneNo	String	e.g.+13729302030	Common info for Car and Hotel type. The telephone number for the Car rental vendor or Hotel.	Not Required.
confirmationNo	String	e.g. 729123	Common info for Car and Hotel type. The confirmation number for the reservation.	Not Required.
rateInfo	String	e.g.100	Common info for Car and Hotel type. Rate info for car rental or hotel room rate per night.	Not Required.
currencyCode	String	e.g. 840	Hotel only. Not applicable for Car. Currency code for rate info.	Not Required.
chainCode	String	e.g. am	Hotel only. Not applicable for Car. Hotel chain code.	Not Required.
guestCount	Integer	e.g. 2	Hotel only. Not applicable for Car. Guest count of hotel reservations.	Not Required.
noOfNights	Integer	e.g. 2	Hotel only. Not applicable for Car. The number of nights of hotel reservations, which should be calculated based on the check-in and check-out dates of the hotel segments. This is optional information that can be provided as input. The system does not do the automatic calculation to override the input value, nor does the validation against it.	Not Required.
noOfRooms	Integer	e.g. 1	Hotel only. Not applicable for Car. The number of rooms of hotel reservations.	Not Required.
roomType	String	e.g. Single room	Hotel only. Not applicable for Car. Room type of hotel reservation.	Not Required.

Address

Name	Type	Value	Description	Validation	Validation Message
locationName	String	e.g. Hilton New York Fashion District Hotel	The location name of the departure or destination location like the airport name, the railway station name, the hotel name.	Not required. For the Hotel/Car segment, it's recommended to provide it because it will be used as the expected location's name. For Air/Rail segment, If not provided, the system will use IATA location's name. Max length is 1024 characters.	◊ Field ['fromAddress.locationName'] length is 1055, exceeds the limit of 1024 characters
country	String	e.g. FR e.g. France	The country's short name or two-letter code of the departure or destination location. The country’s short name comes from ISO_3166-2. https://://en.wikipedia.org/wiki/ISO_3166-2	Required if there is no IATA code or the system can't locate a valid IATA location based on the IATA code. It's recommended to provide a two-letter code of the country.	◊ Field ['fromAddress.country'] is empty ◊ Field ['fromAddress.country'] value AB is invalid
city	String	e.g. Paris	The city name of the departure or destination location.	Not Required. If there is no IATA code or the system can't locate a valid IATA location based on the IATA code, it's required to provide a city or a street address or a geo-location.	Field ['fromAddress.latitude'], Field ['fromAddress.longitude'], Field ['fromAddress.streetAddress'] and Field ['fromAddress.city'] are empty
state	String	e.g. New York e.g. NY	The state name or US state code of the departure or destination location.	Not Required.	◊ Field ['fromAddress.state'] value New York11 is invalid
streetAddress	String	e.g. 152 West 26th Street	The street or address info of the departure or destination location.	If there is no IATA code or the system can't locate a valid IATA location based on the IATA code, it's required to provide a city or a street address or a geo-location. Max length is 1024 characters.	◊ Field ['fromAddress.streetAddress'] length is 1505, exceeds the limit of 1024 characters
postalCode	String	e.g. 10001	The postal code of the departure or destination location.	Not Required.
latitude	Number	e.g. 35.60	A decimal degrees latitude value of the departure or destination location. [-90,+90]	Not Required. If there is no IATA code or the system can't locate a valid IATA location based on the IATA code, it's required to provide a city or a street address or a geo-location.	◊ "Field ['fromAddress.latitude'] value 99.745529 is invalid
longitude	Number	e.g -112.432	A decimal degrees longitude value of the departure or destination location. [-180,+180]	If there is no IATA code or the system can't locate a valid IATA location based on the IATA code, it's required to provide a city or a street address or a geo-location.	◊ Field ['fromAddress.longitude'] value -199.745529 is invalid".

Passengers/TravelArranger

Name	Type	Value	Description	Validation	Validation Message
contactId	String	2419011	The contact Id from EB Suite.	Not Required. Max length is 20 characters.	Field ['passengers.contactId'] length is 30, exceeds the limit of 20 characters.
employeeId	String	e.g. E 001	The employee Id of the passenger. The client can set the value as the contact external id from EB Suite.	Not Required. Max length is 50 characters.	Field ['passengers.employeeId'] length is 72, exceeds the limit of 50 characters
firstName	String	e.g. Jack	The first name of the passenger.	Not Required. Max length is 40 characters.	Field ['passengers.firstName'] length is 72, exceeds the limit of 40 characters
middleName	String	e.g. B.	The middle name of the passenger.	Not Required. Max length is 40 characters.	Field ['passengers.middleName'] length is 72, exceeds the limit of 40 characters!
lastName	String	e.g. William	The last name of the passenger.	Not Required. Max length is 40 characters.	Field ['passengers.lastName'] length is 72, exceeds the limit of 40 characters!
phoneNumbers	Array		The list of the phone numbers of the passenger.	Not Required.
emailAddresses	Array of String	["[email protected]", "[email protected]"]	The list of the email addresses of the passenger.	Not Required. Max length is 80 characters for each email address.	◊ Field passengers.emailAddresses length is 91, exceeds the limit of 80 characters ◊ Field passengers.emailAddresses value [email protected] is invalid
extendedInfo	Object		Extended information at the passenger level. All fields inside the object are optional, as extra information for the system. It does not impact the existing ones. Please note that even though it's also available for the travel arrangers, it is not intended for them, so just ignore the extended info for travel arrangers.	Not required.

Passenger ExtendedInfo

Field Name	Data Type	Values	Description	Validation
externalTravelerId	Integer	e.g. 10001	The external id of the passenger for tracking purposes.	Not Required.
isExpat	Boolean	◊ true ◊ false ◊ null	Expat flag for the passenger. When the input value is True, it means the passenger is an Expatriate.	Not Required.
vipStatusCode	String	e.g. vip	VIP status code for the passenger.	Not Required.
jobBand	String	e.g. PB8	Job band.	Not Required.
jobTitle	String	e.g. Senior Engineer	Job title.	Not Required.
clusterTag	String	e.g. Engineering	Cluster tag, which can be used to categorize the passenger.	Not Required.
emergencyContacts	Array		List of emergency contacts for the passenger.	Not Required.

Passenger EmergencyContact

Field Name	Data Type	Values	Description	Validation
externalNextOfKinId	Integer	e.g. 10001	Emergency contacts themselves do not have to travel. The external id of the emergency contact, for tracking purposes.	Not Required.
relationship	String	e.g. partner	Emergency Contact's relationship with the passenger.	Not Required.
firstName	String	e.g. Alice	Emergency Contact's first name.	Not Required.
lastName	String	e.g. Williams	Emergency Contact's last name.	Not Required.
telHome	String	e.g. +15712345678	Emergency Contact's home phone.	Not Required.
telWork	String	e.g. +15712345677	Emergency Contact's work phone.	Not Required.
telCell	String	e.g. +15712345676	Emergency Contact's cell phone.	Not Required.
emailAddress	String	e.g. [email protected]	Emergency Contact's email.	Not Required.
address	String	e.g. 152 West 26th Street	Emergency Contact's address info.	Not Required.

PhoneNumber

Field Name	Data Type	Values	Description	Validation	Validation Message
phoneNumber	Number	e.g. 1571634908 e.g. +861571634 9087	The phone number .	phoneNumber with calling country code, e.g. +8615716349087 { "phoneNumber": "+8615716349087" } phoneNumber without calling country code but with countryName. e.g.: {"phoneNumber": "15716349087", "countryName": "CN"}	Field ['passengers.pho neNumbers'] length is 23, exceeds the limit of 20 characters
countryName	String	e.g. CN, China	The country's short name or two- letter code of the phone number.	Not Required. The non-blank value must be a valid value.

Notes

Address And Timezone Adoption Rules

Address and geolocation calculation

In order for a segment and travel locations to be created successfully, the system needs enough information to geocode the created locations.

Geolocation (latitude and longitude) can be provided using either the address fields (fromAddress and toAddress) OR using the IATA code (fromIataCode and toIataCode).
The address can be provided using either the address field (fromAddress and toAddress) OR using the IATA code (fromIataCode and toIataCode).
A valid address requires a valid country AND either a valid street address, city or geo-location; if the country is United States, a valid State must be provided.

Depending on the segment type, geolocation, address, or the IATA code will take priority in calculating other fields.

For segments of the Air/Rail type:

When setting addresses, the system will consider the provided IATA code (fromIataCode and toIataCode) as a higher priority than the address field (fromAddress and toAddress).

If an IATA code is provided and located by the system, then it will set up an address from that IATA location. The IATA location's name will be used to set the expected location's street address.
If no valid IATA code is found or not provided, the system uses available information in the address fields (fromAddress and toAddress) if present and valid.

When settings geolocation, the system will regard the provided information in the following order to set the geolocation of the created locations:

Valid latitude and longitude values are given preference. (provided latitude and longitude which are different from 0.0 are considered valid)
Next comes IATA codes. (fromIataCode and toIataCode),
Lastly considered are details in from the address fields (fromAddress and toAddress) - The geolocation is calculated after the travel location are created.

For segments of the Car/Hotel type:

When setting addresses:

Priority is given to from/to addresses over IATA codes.
The system uses available information in the address fields (fromAddress and toAddress) if present and valid ; otherwise attempt is made to use the available IATA code when creating the travel locations

For setting geolocation:

Valid latitude and longitude values are given preference. (provided latitude and longitude which are different from 0.0 are considered valid)
Then come details in from the address fields (fromAddress and toAddress); The geolocation is calculated after the travel location are created.
Last consideration - use of the IATA code if provided.

Time zone and local time Calculation:

The time zone links and calculates the local time of the created travel location with the DateTime provided in UTC. The IATA code time zone can be used, however, the time zone cannot be calculated from the address or the provided geolocation.

For Air and Train segment, highest priority is given to the IATA code to set the time zone, else resorting to use the provided DateTime, DateTimeLocal and TimeZone.
For Hotel and Car Segments, if the address information (fromAddress and toAddress) is provided, the provided DateTime, DateTimeLocal and TimeZone, will be used. Fallback option is to use the IATA code (if provided).

If the IATA code is used, then it will use the IATA timezone to calculate the local time of the start date and end date for the travel locations. The Date/Time (fromDateTime and toDateTime) OR the Date Time Local (fromDateTimeLocal and toDateTimeLocal) must also be provided.

Otherwise,

If Date/Time (fromDateTime and toDateTime) is provided, it will be used. No other fields are required.
If Date/Time (fromDateTime and toDateTime) is not provided, Date Time Local (fromDateTimeLocal and toDateTimeLocal) AND time zone (fromTimeZone and toTimeZone) are required.