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. |
TravelAgencyInfo
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
Date Time Adoption Rule
The system will regard the UTC date-time string (fromDateTime and toDateTime) as a higher priority than the local date-time string (fromDateTimeLocal and toDateTimeLocal).
-
If the UTC date time string is provided with a valid format and the from date-time is before the to date-time, the system will use it and make validation of the travel segment's date-time pass.
-
If the UTC date time string is not provided, the local date-time string (fromDateTimeLocal and toDateTimeLocal) is provided with a valid format, and there is a timezone from the timezone field (fromTimeZone and toTimeZone) or from the IATA Location's timezone, the system will use it and make the validation pass. Otherwise, this segment data will be ignored and the system will not generate the expected locations for it.
Address And Timezone Adoption Rule
In order for a segment and expected locations to be created successfully, the system need an address (for geolocation) and a time zone (to calculate the local time).
The address can be either provided using the address field (fromAddress and toAddress) OR using the IATA code (fromIataCode and toIataCode).
Time zone can be calculated from the IATA code, however, it cannot be calculated from the address.
Depending on the segment type, the address or the IATA code will be taken in priority.
For segments of the Air/Rail type:
The system will regard the IATA code (fromIataCode and toIataCode) as a higher priority than the address field (fromAddress and toAddress) when setting address, geolocation and time zone.
• If the IATA code is provided and the system can locate an IATA location based on the IATA code, then the system will set the created expected location's name, country, state, city, latitude, longitude and the local time zone from the IATA location's name, country, state, city, latitude, longitude, and timezone. The IATA location's name will be used to set the expected location's street address.
• If the IATA code is not provided or the system can't locate an IATA location based on the IATA code, then the system will try to set the Country, State, City, Address and time zone from the provided information. If there is a valid country and a valid street address, city or geo-location, then the segment data will be ingested successfully.
Note: if the country is United States, a valid State must be provided.
If there is a valid latitude and longitude provided, it will be used otherwise, to calculate the latitude and longitude, the system will try to use the address information from the address field (fromAddress and toAddress) if provided.
For segments of the Car/Hotel type:
The system will regard the address fields (fromAddress and toAddress) as a higher priority than the IATA code (fromIataCode and toIataCode) when setting address and time zone.
If there is a valid country and a valid street address, city or geo-location (Note: if the country is United States, a valid State must be provided), OR valid IATA code the segment data will be ingested successfully.
• Address and Geolocation calculation:
If some address information is provided, in the address field (fromAddress and toAddress) then the system will try to set the Country, State, City, Address and time zone from the provided information.
If a valid Latitude and longitude is provided it will be used, otherwise geolocation will be calculated from the provided address.
If no information is provided in the address fields (fromAddress and toAddress) the system will attempt to use the IATA code. The system will set the created expected location's name, country, state, city, latitude, longitude and the local time zone from the IATA location's name, country, state, city, latitude, longitude, and timezone.
• Time zone Calculation:
If the address information (fromAddress and toAddress) is provided,
- 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.
If the address information (fromAddress and toAddress) is not provided and the IATA code is used, then the system will adopt the IATA location's name, country, state, city, latitude, longitude, and timezone and use them as the expected location's location name, country, state, city, latitude, longitude and the local time zone of the arrival date and expired date.
The Date/Time (fromDateTime and toDateTime) OR the Date Time Local (fromDateTimeLocal and toDateTimeLocal) must also be provided