This document represents the API that will be used to manage your travelers as well as distribute travel apps to them. It provides an overview of the different methods and specifies the requested format.
Latest Version (see change log for more details): 3.1
For questions, feel free to contact us at [email protected]
Access to the API
| Environment | API Base Url | |
|---|---|---|
| Sandbox | https://sandbox.mtrip.com | A sandbox API key is required |
| Production | https://api.mtrip.com https://api1.mtrip.com |
(North American server) (European server) |
Security and Authentication
All requests to the API should be made through https only.
For security reasons, the minimum TLS version is 1.2
Authentication to the API is done using HTTP Basic Auth.
Set your API key as the username and leave the password field empty.
Note that the API keys are different for the sandbox and production environment.
Some endpoints may not be accessible depending on your account settings.
Make sure your request “Content-Type” is set to “application/json”
For security reasons, the minimum TLS version is 1.2
Authentication to the API is done using HTTP Basic Auth.
Set your API key as the username and leave the password field empty.
Note that the API keys are different for the sandbox and production environment.
Some endpoints may not be accessible depending on your account settings.
Make sure your request “Content-Type” is set to “application/json”
Versioning
The API version will change whenever we make modifications to the API that are not backward compatible.
Updating trips
To update a trip, the full itinerary should be pushed again through the API. Elements that have been entered manually on the CMS platform will not be deleted or modified.
Trips that are in the past cannot be updated as a safeguard to prevent old and new data from colliding. If a past trip needs to be updated after it has technically finished, it can be deleted either manually or through the API (details in the Trip Method section) and then the updated trip can be re-pushed.
Methods
Trip Method
The Trip object includes information about a trip:
Besides the basic informations (name, dates…), it has 5 relationships: travelers, flight, car_rental, train, transports, destinations, accommodations, documents.
travelers relationship: set of travelers participating in the trip.
transports relationship: different transport modes used during the trip (e.g. boat, taxi…).
accommodations relationship: accommodations used during the trip.
destinations relationship: different destinations visited by the travelers, along with the different scheduled activities.
documents relationship: documents (invoice, e-ticket, voucher, etc) which should be made available within the mobile app.
| http method | endpoint | description | data |
|---|---|---|---|
| POST | /v1/trips | create a new trip | a json containing the representation of a Trip Object |
| DELETE | /v1/trips | delete a trip | a json containing the identifier parameter associated with the key “identifier” |
Travelers Method
The traveler method is used to add new travelers to the CMS.
| http method | endpoint | description | data |
|---|---|---|---|
| POST | /v1/travelers | create a new traveler | a json containing the representation of a Travelers object |
| GET | /v1/travelers/mobile_app_link?user_identifier=[USER IDENTIFIER]&trip_identifier=[TRIP IDENTIFIER] | get the mobile app download link for a specific traveler of a specific trip. The links include the encrypted travelers’ login credentials. | [USER IDENTIFIER] should match Travelers Object > identifier. [TRIP IDENTIFIER] should match Trip Object > identifier |
| DELETE | /v1/travelers | delete a traveler | a json containing the representation of a Travelers object |
Accounts Method
The Accounts method is used to create and updates agencies/profiles/accounts for a single mobile app. Each account can be configured differently in terms of branding, features and layout. Each itinerary (Trip Object) is linked to one account. The API lets you list the existing accounts and create/update accounts.
| http method | endpoint | description | data |
|---|---|---|---|
| GET | /v1/accounts | List all existing accounts | None |
| POST | /v1/accounts | Create new accounts. Response contains its mtrip_account_id | A json containing the representation of an Account Object |
| PUT | /v1/accounts | Update an existing account | A json containing the representation of an Account Object Query parameters should contain a combination of mtrip_account_id, office_id and corporate_id allowing identification of updated account. |
Inventories Method
The inventories method is used to create inventory (accommodation and activities) to the CMS.
| http method | endpoint | description | data |
|---|---|---|---|
| POST | /v1/inventories | create inventory object | a json containing the representation of a inventory object |
API Status
Let you check the status of the mTrip API – No authentification required.
| http method | endpoint | description | data |
|---|---|---|---|
| GET | /v1/health | http response code (200: everything works smoothly – other codes should be considered as an error) |
Push Notifications
You can use the API to send push notifications to travelers for marketing, support or information purposes.
Make sure to only send push notifications to travelers who you have already sent an itinerary to through the API.
Please contact us to activate this option.
| http method | endpoint | description | data |
|---|---|---|---|
| POST | /v1/travelers/notifications | Send a push notification to travelers based on their email or identifier | a json containing either the traveler(s) email(s) or identifier(s), the notification text and optionally a link which will be opened if the traveler presses the notification. |
External Bookings
Retrieve all the bookings added by travelers and booked externally.
| http method | endpoint | description | data |
|---|---|---|---|
| POST | /v1/external_bookings | Returns a json with the segment details | A json that contains a date range of the bookings that have been added (compulsory), filtered by account (optional). |
Object Format
This section displays the different fields that define the objects. Each field has a type which is either a basic type (e.g. string, int…) , or an array of other objects (e.g. an array of travelers).
The date type is a string date format ‘YYYY-MM-DDTHH:mm:ssZ’ (ISO 8601).
The time type is a string date format ‘HH:mm’.
The location type is an object with two fields, latitude takes values in range [-90,90] and longitude takes values in range [-180,180]
All strings must be UTF-8 encoded.
Trip Object
The Trip Object includes all the information about a specific trip (travelers, transportation, accommodation, etc.). A trip must be linked to an account. Accounts can be a corporate client for TMC, a brand for a leisure agency or any segmentation.
To link a trip, the Trip Object must include either the mtrip_account_id which is generated by the mTrip platform and available in the accounts settings (Connectivity tab) or a combination of office_id and/or corporate_id (make sure if you provide those, to add them in one of the accounts settings). Feel free to contact us for further details.
Sandbox mode (https://sandbox.mtrip.com): use the mtrip_account_id – Production mode (https://api.mtrip.com or https://api1.mtrip.com): do not use mtrip_account_id but office_id and optionally corporate_id.
| Name | Description | Type | Optional |
|---|---|---|---|
| travelers | An array of travelers | [traveler] | NO |
| name | The name of the guide displayed to the travelers | string | YES |
| trip_type | Type of layout applied to the trip: type_2 for Tours & MICE – Wide View / cruise type_3 for Tours & MICE – Slim View type_4 for Independent Travelers (Leisure & Business) |
string | YES |
| mtrip_account_id | The id of the account (agency, brand, corporate client, profile) in mTrip CMS. Only needed if the authenticated user manages multiple agencies. Accounts are created in the CMS and may not be available for your account. | integer | YES (if office_id and/or corporate_id are provided) |
| office_id | string | YES (if mtrip_account_id is provided) | |
| corporate_id | string | YES (if mtrip_account_id is provided) | |
| identifier | The reference id of the guide in your system. Use to retrieve a guide after being added (e.g. to update the informations). | string | YES |
| start_date | the start date of the trip | date | YES (depending on your account settings it may be mandatory) |
| end_date | the end date of the trip | date | YES (depending on your account settings it may be mandatory) |
| description | A description of the trip that will be displayed to the travelers. It will be displayed in the app as “Trip Information” | string | YES |
| destinations | An array of destinations | [destination] | NO |
| flights | An array of flights | [flights] | YES |
| car_rentals | An array of car rentals | [car_rentals] | YES |
| transports | An array of transports | [transport] | YES |
| cruises | An array of cruises | [cruises] | YES |
| accommodations | An array of accommodations | [accommodation] | YES |
| documents | An array of documents | [document] | YES |
| trip_information_documents | Trip attachement object | Trip attachement object | YES |
| picture_url | Trip cover picture (value should be an URL, size should be 640px by 480px – .jpg or .png format, if larger will be cropped) | string | YES |
| sort_items_by_position | if YES, item positions will override dates | boolean | YES |
| template_id | identifier of the itinerary template (daily itineraries for organised tours) | string | YES |
| status | status of the trip (value: draft or published) |
string | YES |
| booking_status | booking status of the trip (value should be: pending, confirmed or cancelled) |
string | YES |
| booking_visibility | indicates if the flight/hotel booking info should be shared among travelers | boolean | YES |
| price_currency | Currency code (used when pricing is attached to the trip) | string | YES (except if pricing is attached to the trip) |
| total_price | Total price to be displayed | float | YES |
| price_note | Comments / note about the pricing | string | YES |
Traveler Object
In the Traveler Object, you have the ability to assign roles to each person in the trip. Each role provides a specific user experience, which depends on the needs of the user.
Available roles for business travel
Traveler: This is the default role and is used for travelers. When they login to the app, they will see their Upcoming Trips and Past Trips (if they have any).
Booker: If you add a Booker to a trip, a My Travelers tab will appear on the trips page when they login to the app. The Booker will be able to see all the trips they booked. They will be able to view their traveler’s itinerary but have no access to specific features like maps, guides, flight alerts, trip journal, etc.
Manager: If you add a Manager to a trip, a My Travelers tab will appear on the trips page when they login to the app. The Manager will be able to see all the trips they booked. They will be able to view their traveler’s itinerary but have no access to specific features like maps, guides, flight alerts, trip journal, etc.
Assistant: If you add an Assistant to a trip, a My Travelers tab will appear on the trips page when they login to the app. The Assistant will be able to see all the trips they booked. They will be able to view their traveler’s itinerary but have no access to specific features like maps, guides, flight alerts, trip journal, etc.
Available roles for leisure travel
Traveler: This is the default role and is used for travelers. When they login to the app, they will see their Upcoming Trips and Past Trips (if they have any).
Tour Leader: The Tour Leader role includes the Traveler role, as well as additional features like the ability to send messages to all members of the trip and locate them in real time.
Booker: If you add a Booker to a trip, a My Travelers tab will appear on the trips page when they login to the app. The Booker will be able to see all the trips they booked. They will be able to view their traveler’s itinerary but have no access to specific features like maps, guides, flight alerts, trip journal, etc.
| Name | Description | Type | Optional |
|---|---|---|---|
| role | User role – possible values: For leisure travel: traveler, booker, tour_leader For business travel: traveler, assistant, booker, agent, approver or, manager |
string | YES (traveler by default) |
| traveler’s email | string | NO | |
| first_name | traveler’s first name | string | NO |
| last_name | traveler’s last name | string | NO |
| identifier | traveler reference id in your system | string | NO |
| password | traveler account password. At least 6 characters, at most 256. | string | YES |
| language | traveler’s language code (two letter ISO language code , e.g. en, fr, es…) | string | YES (en by default) |
| phone | Traveler’s cell phone number, with country code (e.g. +1 for US/Canada). will be used to send SMS invitation | string | YES |
| send_invitation_type | Specify if an invitation email is sent to the traveler and at which frequency: 0: don’t send invitation 1: send an invitation when the itinerary is created and at each update 2: send an invitation only when the itinerary is created |
integer | YES (2 by default) |
| send_invitation (deprecated) | Specify if an invitation email is sent to the traveler after his account is created | boolean | YES (FALSE by default) |
| send_invitation_at | Schedule the date/time the invitation will be sent (send_invitation needs to be true) | string | YES |
| send_invitation_sms | Specify if an invitation SMS is sent to the traveler after his account is created. phone needs to be defined and send_invitation needs to be true. Note: additional fees may occur – please contact us to activate this feature |
boolean | YES (FALSE by default) |
| guides | An array of existing guide identifiers | string | YES |
| is_tour_leader (deprecated) | Specify if the traveler has the status of tour leader for this specific trip. Tour Leader feature needs to be activated in the agency settings. | boolean | YES |
| booking_reference | Booking reference specific to the traveler | string | YES |
| FOR BUSINESS TRAVELERS: see role attribute above |
|||
| manager_first_name | Traveler’s manager first name (used for trip approval only) | string | YES |
| manager_last_name | Traveler’s manager last name (used for trip approval only) | string | YES |
| manager_email | Traveler’s manager email (used for trip approval only) | string | YES |
| assistant_first_name | Traveler’s assistant first name | string | YES |
| assistant_last_name | Traveler’s assistant last name | string | YES |
| assistant_email | Traveler’s assistant email | string | YES |
Destination Object
The Destination object should only include final destinations: neither stopovers nor the departure location.
| Name | Description | Type | Optional |
|---|---|---|---|
| name | Name of the destination | string | NO |
| locode | LOCODE code of the destination – MUST be a city code – see https://www.unece.org/cefact/locode/service/location.html | string | YES |
| country_iso_code | ISO code of the destination’s country | string | YES |
| start_date | the start date of the trip in the destination | date | YES |
| end_date | the end date of the trip in the destination | date | YES |
| activities | An array of activities | [activity] | YES |
| picture_url | URL of a picture, should be 640px by 480px – .jpg or .png format, if larger will be cropped | string | YES |
| description | description of the destination, it should be valid html text. | string | YES |
| location | Geo-location of the destination | location | YES |
| position | position of the item in the itinerary | integer | NO if sort_items_by_position (Guide Object) is TRUE |
If “name” cannot be linked to an existing offline guide: picture_url, description, and location will be used to display information about the destination in the trip screen of the app, otherwise this properties will be ignored.
Flight Object
| Name | Description | Type | Optional |
|---|---|---|---|
| departure_date | Departure date | datetime | NO |
| airline_iata | IATA code of the airline | string | NO for flights |
| flight_number | The number identifying the flight | string | NO for flights |
| booking_reference | The booking reference for the flight, it should be the airline PNR record locator used for online checkin | string | YES |
| departure_city | The city from where the transport leaves | string | NO |
| arrival_city | The city to where the transport goes | string | NO |
| airline | The name of the airline | string | YES |
| departure_airport | The departure airport of a flight or the departure station for other transport mode | string | YES |
| departure_airport_iata | IATA code of the airport | string | YES |
| arrival_airport | The arrival airport or the arrival station for other transport mode | string | YES |
| arrival_airport_iata | IATA code of the airport | string | YES |
| departure_terminal | The departure terminal | string | YES |
| arrival_terminal | The arrival terminal | string | YES |
| arrival_date | Arrival date | datetime | YES |
| comments | Information about the transport mode displayed to the traveler | string | YES |
| duration | duration of the trip in seconds. If not set, the duration will be automatically computed from the dates. Set to -1 if you want don’t have the information and the dates may lead to the wrong duration (timezone difference between start and end points) | int | YES |
| departure_location | Departure geo-location | location | YES |
| arrival_location | Arrival geo-location | location | YES |
| position | position of the item in the itinerary | integer | NO if sort_items_by_position (Guide Object) is TRUE |
| active_for_every_traveler | If false, provide information in traveler_details below to specify which travelers should be associated to this transport | boolean | YES (default true) |
| travelers_details | An array of Transport Traveler Details | [transport_traveler_detail] | NO if active_for_every_traveler is set to YES |
| aircraft | Aircraft model | string | YES |
| operator | Name of the operating airline | string | YES |
| operator_number | string | YES | |
| identifier | segment identifier | string | YES (except if pricing is attached to the trip) |
| services | list of attached services | array | YES |
Transport Traveler Detail Object
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
| reservation_reference | Reservation or confirmation number (airline booking reference for flights) | string | YES |
| e_ticket | e-Ticket number | string | YES |
| class | Value should be: Economy, Premium Economy, Business, First | string | YES |
| seat_number | Seat number | string | YES |
| baggage_allowance | Text describing the baggage allowance | string | YES |
| benefits | string | YES | |
| cancellation_conditions | Cancellation terms | string | YES |
| vcc_id | Virtual credit card ID | string | YES |
| vcc_provider | Virtual credit card provider. Value should be: troovo or conferma | string | YES |
| frequent_flyer_number | Traveler’s frequent flyer number | string | YES |
Car Rental Object
| Name | Description | Type | Optional |
|---|---|---|---|
| pickup_date | Pickup date | datetime | NO |
| reservation_reference | The booking number or reservation reference | string | YES |
| pickup_city | The Pickup city | string | NO |
| dropoff_city | Drop off city | string | NO |
| vendor | The name of the car rental company (ie. Hertz, Avis, etc.) | string | YES |
| pickup_station | The Pickup station | string | YES |
| pickup_airport | The Pickup airport | string | YES |
| pickup_airport_iata | IATA code of the airport | string | YES |
| dropoff_airport | The drop off airport | string | YES |
| dropoff_station | The drop off station for other transport mode | string | YES |
| dropoff_airport_iata | IATA code of the airport | string | YES |
| dropoff_date | Drop off date | datetime | YES |
| comments | Information about the transport mode displayed to the traveler | string | YES |
| duration | duration of the trip in seconds. If not set, the duration will be automatically computed from the dates. Set to -1 if you want don’t have the information and the dates may lead to the wrong duration (timezone difference between start and end points) | int | YES |
| pickup_location | Pickup geo-location | location | YES |
| dropoff_location | Drop off geo-location | location | YES |
| position | position of the item in the itinerary | integer | NO if sort_items_by_position (Guide Object) is TRUE |
| active_for_every_traveler | If false, provide information in traveler_details below to specify which travelers should be associated to this transport | boolean | YES (default true) |
| travelers_details | An array of Transport Traveler Details | [transport_traveler_detail] | NO if active_for_every_traveler is set to YES |
| car_type | Type of car (ie: mid-size car) | string | YES |
| pickup_address | Address where the car will be picked up | string | YES |
| dropoff_address | Address where the car will be dropped off | string | YES |
| identifier | segment identifier | string | YES (except if pricing is attached to the trip) |
Transport Traveler Detail Object
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
| reservation_reference | Reservation or confirmation number (airline booking reference for flights) | string | YES |
| benefits | string | YES | |
| cancellation_conditions | Cancellation terms | string | YES |
| vcc_id | Virtual credit card ID | string | YES |
| vcc_provider | Virtual credit card provider. Value should be: troovo or conferma | string | YES |
| reward_program_number | Traveler’s vendor reward program number | string | YES |
Train Object
| Name | Description | Type | Optional |
|---|---|---|---|
| departure_date | Departure date | datetime | NO |
| train_number | The number identifying the train | string | YES |
| reservation_reference | The booking number or reference for the train | string | YES |
| departure_city | The city from where the transport leaves | string | NO |
| arrival_city | The city to where the transport goes | string | NO |
| railway_company | The name of the company operating the train | string | YES |
| departure_station | The departure station for other transport mode | string | YES |
| departure_airport | The departure airport of a flight or the departure station for other transport mode | string | YES |
| departure_airport_iata | IATA code of the airport | string | YES |
| arrival_airport | The arrival airport or the arrival station for other transport mode | string | YES |
| arrival_station | The arrival station for other transport mode | string | YES |
| arrival_airport_iata | IATA code of the airport | string | YES |
| arrival_date | Arrival date | datetime | YES |
| comments | Information about the transport mode displayed to the traveler | string | YES |
| duration | duration of the trip in seconds. If not set, the duration will be automatically computed from the dates. Set to -1 if you want don’t have the information and the dates may lead to the wrong duration (timezone difference between start and end points) | int | YES |
| departure_location | Departure geo-location | location | YES |
| arrival_location | Arrival geo-location | location | YES |
| position | position of the item in the itinerary | integer | NO if sort_items_by_position (Guide Object) is TRUE |
| active_for_every_traveler | If false, provide information in traveler_details below to specify which travelers should be associated to this transport | boolean | YES (default true) |
| travelers_details | An array of Transport Traveler Details | [transport_traveler_detail] | NO if active_for_every_traveler is set to YES |
| identifier | Segment identifier | string | YES (except if pricing is attached to the trip) |
Transport Traveler Detail Object
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
| reservation_reference | Reservation or confirmation number (airline booking reference for flights) | string | YES |
| class | Value should be: Economy, Premium Economy, Business, First | string | YES |
| seat_number | Seat number | string | YES |
| baggage_allowance | Text describing the baggage allowance | string | YES |
| benefits | string | YES | |
| cancellation_conditions | Cancellation terms | string | YES |
| vcc_id | Virtual credit card ID | string | YES |
| vcc_provider | Virtual credit card provider. Value should be: troovo or conferma | string | YES |
| reward_program_number | Reward program number | string | YES |
Transport Object
| Name | Description | Type | Optional |
|---|---|---|---|
| transport_type | The transportation mode type | enum{Boat Bus Car Ferry Shuttle Taxi Tram Limo} | NO |
| departure_date | Departure date | datetime | NO |
| departure_has_time | Specify if the departure_date includes transport departure time | boolean | YES |
| airline_iata | IATA code of the airline | string | NO for flights |
| transport_number | The number identifying the transport, e.g. the flight number for a flight, the train number for a train… | string | NO for flights |
| reservation_reference | The booking number for the transportation – for flights, it should be the airline PNR record locator used for online checkin | string | YES |
| departure_city | The city from where the transport leaves | string | NO |
| arrival_city | The city to where the transport goes | string | NO |
| airline_company | The name of the airline | string | YES |
| departure_station | The departure station for other transport mode | string | YES |
| departure_airport | The departure airport of a flight or the departure station for other transport mode | string | YES |
| departure_airport_iata | IATA code of the airport | string | YES |
| arrival_airport | The arrival airport or the arrival station for other transport mode | string | YES |
| arrival_station | The arrival station for other transport mode | string | YES |
| arrival_airport_iata | IATA code of the airport | string | YES |
| departure_terminal | The departure terminal, only for flights | string | YES |
| arrival_terminal | The arrival terminal, only for flights | string | YES |
| arrival_date | Arrival date | datetime | YES |
| arrival_has_time | Specify if the arrival_date includes transport arrival time | boolean | YES |
| comments | Information about the transport mode displayed to the traveler | string | YES |
| duration | duration of the trip in seconds. If not set, the duration will be automatically computed from the dates. Set to -1 if you want don’t have the information and the dates may lead to the wrong duration (timezone difference between start and end points) | int | YES |
| departure_location | Departure geo-location | location | YES |
| arrival_location | Arrival geo-location | location | YES |
| position | position of the item in the itinerary | integer | NO if sort_items_by_position (Guide Object) is TRUE |
| active_for_every_traveler | If false, provide information in traveler_details below to specify which travelers should be associated to this transport | boolean | YES (default true) |
| travelers_details | An array of Transport Traveler Details | [transport_traveler_detail] | NO if active_for_every_traveler is set to YES |
| transport_craft | Type of transport. Mainly used for car rental (ie: mid-size car) | string | YES |
| operator_name | Name of the operator | string | YES |
| operator_number | string | YES | |
| identifier | Segment identifier | string | YES (except if pricing is attached to the trip) |
| services | list of attached services (for flights only) | array | YES |
Transport Traveler Detail Object
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
| reservation_reference | Reservation or confirmation number (airline booking reference for flights) | string | YES |
| e_ticket | e-Ticket number | string | YES |
| class | Class of the transport | string | YES |
| seat_number | Seat number | string | YES |
| baggage_allowance | Text describing the baggage allowance | string | YES |
| benefits | string | YES | |
| cancellation_conditions | Cancellation terms | string | YES |
| vcc_id | Virtual credit card ID | string | YES |
| vcc_provider | Virtual credit card provider. Value should be: troovo or conferma | string | YES |
| frequent_flyer_number | Traveler’s frequent flyer number | string | YES |
Cruise Object
Cruise vendors naming: click here – Cruise ships naming: click here
| Name | Description | Type | Optional |
|---|---|---|---|
| name | name of the cruise | string | NO |
| picture_url | url of the cruise picture | string | YES |
| departure_date | Departure date | datetime | NO |
| departure_has_time | Specify if the departure_date includes cruise departure time | boolean | YES |
| departure_city | The city from where the cruise leaves | string | NO |
| departure_address | Address of the initial port of departure | string | YES |
| arrival_date | Arrival date | datetime | NO |
| arrival_has_time | Specify if the arrival_date includes cruise arrival time | boolean | YES |
| arrival_city | Address of the final port of arrival | string | NO |
| arrival_address | Address of the final port of arrival | string | YES |
| supplier_name | Cruise line | string | NO |
| ship_name | Name of the ship | string | NO |
| destinations | An array of port of call | [destination] | YES |
| reservation_reference | Booking reference | string | YES |
| comments | Information about the cruise displayed to the traveler | string | YES |
| active_for_every_traveler | If false, provide information in traveler_details below to specify which travelers should be associated to this cruise | boolean | YES (default true) |
| travelers_details | An array of Cruise Traveler Details | [transport_traveler_detail] | NO if active_for_every_traveler is set to YES |
| identifier | segment identifier | string | YES (except if pricing is attached to the trip) |
Cruise Traveler Detail Object
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
| reservation_reference | Reservation or confirmation number | string | YES |
| class | string | YES | |
| deck | string | YES | |
| cabin | string | YES |
Accommodation Object
| Name | Description | Type | Optional |
|---|---|---|---|
| name | Name of the accommodation | string | NO |
| from_date | Check-in date | date | NO |
| to_date | Check-out date | date | NO |
| check_in_time | Check-in Time | time | YES |
| check_out_time | Check-out Time | time | YES |
| info | Information about the accommodation displayed to the user | text | YES |
| location | Geo-location of the accommodation | location | YES |
| address | Address of the accommodation | string | YES (will have no effect if “mtrip_id” is present ) |
| picture_url | URL of a picture, should be 640px by 480px – .jpg or .png format, if larger will be cropped | string | YES (will have no effect if “mtrip_id” is present ) |
| type_of_room | The type of room booked | string | YES |
| booking_number | The booking number for the accommodation | string | YES |
| city | Name of the destination to which the accommodation should be attached to. | string | NO if “mtrip_id” is not present |
| phone | Phone number (recommended format: +[country code] [phone number]) | string | YES |
| Email address | string | YES | |
| chain_code | Hotel GDS code (used to display the hotel logo within the app) | string | YES |
| active_for_every_traveler | If false, provide information in traveler_details below to specify which travelers should be associated to accommodation | boolean | YES (default true) |
| travelers_details | An array of Accommodation Traveler Details | [accommodation_traveler_detail] | NO if active_for_every_traveler is set to FALSE |
| inventory_id | Only if Inventory Object is used | text | YES |
Accommodation Traveler Detail Object
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
| booking_number | The booking number for the accommodation | string | YES |
| type_of_room | The type of room booked | string | YES |
| info | Information about the accommodation displayed to the user | string | YES |
| benefits | special benefits associated to the accommodation (ie: free wifi, free upgrade upon availability, etc.) | string | YES |
| cancellation_conditions | cancellation terms | string | YES |
| vcc_id | Virtual credit card ID | string | YES |
| vcc_provider | Virtual credit card provider. Value should be troovo or conferma | string | YES |
Document Object
You can attach travel documents to each trip, they will be available offline within the mobile app: vouchers, reservations, etickets, coupons, etc.
| Name | Description | Type | Optional |
|---|---|---|---|
| url | URL of the document (document can be a .jpeg, .png, .pdf, .doc(x), .txt) | string | NO |
| name | Name of the document | string | YES (if empty we will use the URL to create the name) |
| description | Description of the document | string | YES |
| travelers | An array of traveler identifiers | [string] | YES (if empty or not defined, all users will receive the document) |
Trip Attachment Object
You can attach travel information and documents (pdf, html/text, link) to each trip, they will be available offline within the mobile app. Trip Attachement Object can contain either multiple template IDs or multiple documents.
| Name | Description | Type | Optional |
|---|---|---|---|
| templates | array of trip attachment template id | array | YES |
| documents | array of trip attachment documents | [documents] | YES |
Documents Object
| Name | Description | Type | Optional |
|---|---|---|---|
| name | document name | string | NO |
| position | the position to display a document in a trip (value: before/after) |
string | NO |
| order | the order to display a document in the document list | integer | NO |
| document_type | type of a document (value: text/link/file) | string | NO |
| text | the content when a document is a text/html | string | YES |
| url | the web link when a document is a link | string | YES |
| file_url | URL of the document (.DOCX, .PDF, .PNG, .JPG and .TXT) | string | YES |
| active_for_every_traveler | If false, provide information in travelers_details below to specify which travelers should be associated to this document | boolean | YES (default true) |
| travelers_details | An array of Activity Traveler Details | [document_traveler_details] | YES if active_for_every_traveler is set to YES |
Traveler Details
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
Activity Object
| Name | Description | Type | Optional |
|---|---|---|---|
| date | Date of activity | date | NO |
| name | Name of the activity | string | YES (this can be omitted if you only want to present an informative text in the “comments” variable |
| start_time | Start time of activity | time | YES |
| end_time | End time of activity | time | YES |
| period | The id of the period of the day when the activity occurs (select day for a day summary) | enum{morning,afternoon,lunch,evening,dinner,day} | YES (will be computed from the start_time if not present) |
| type | The type id of the activity | [“active”, “art_museum”, “birthday_reminder”, “car_rental”, “classic”, “coffee_break”, “concert”, “conference”, “cruises”, “culinary_experience”, “cultural_visit”, “discovery”, “entertainment”, “entrances_fees”, “excursion”, “family_whereabouts”, “flight”, “great_for_children”, “guides”, “indoor_exercise”, “local_flavor”, “meal”, “nature”, “not_classified”, “on_water”, “outdoor_activity”, “phone_call”, “riding_tour”, “ships_riverboats”, “shopping”, “sightseeing”, “spa”, “sport”, “tennis”, “train”, “transport”, “trekking”, “water_sport”, “working_session”, “workshop”] | YES |
| comments | Information / Description of the activity displayed to the user | string | YES |
| location | Geo-location of the activity | location | YES |
| duration | Duration of the activity (in minutes) | int | YES |
| position | Position within the period (select 0 for a day summary) | int | YES |
| address | Address of the activity | string | YES |
| associated_places | An array of place ids (in mTrip CMS) associated with the visit. | int | YES |
| picture_url | URL of a picture, should be 640px by 480px – .jpg or .png format, if larger will be cropped | text | YES |
| inventory_id | Only if Inventory Object is used | string | YES |
| active_for_every_traveler | If false, provide information in travelers_details below to specify which travelers should be associated to this activity | boolean | YES (default true) |
| travelers_details | An array of Activity Traveler Details | [activity_traveler_detail] | NO if active_for_every_traveler is set to YES |
| optional_booking | Link for optional activities booking | text | YES |
Activity Traveler Detail Object
| Name | Description | Type | Optional |
|---|---|---|---|
| traveler_identifier | Identifier of the traveler | string | NO |
Service Object
Service object is attached to a flight object. For example a lounge access or a fast track pass.
| Name | Description | Type | Optional |
|---|---|---|---|
| service_type | type of service. Available values: fast, lounge, meet, park, vip, health, trsf, tour, boat | string | NO |
| start_date | start date | date | NO |
| start_time | start time | time | NO |
| end_date | end date | date | NO |
| end_time | end time | time | NO |
| title | service name | string | NO |
| description | service description | string | YES |
| city | city | string | YES |
| address | address | string | YES |
| latitude | latitude | float | YES |
| longitude | longitude | float | YES |
| airline_iata | airline IATA code | string | YES |
| airport_iata | airport IATA | string | YES |
Price Object
| Name | Description | Type | Optional |
|---|---|---|---|
| price | price value | float | NO |
| segment_identifiers | all segments included for this price (flights, hotel, etc.) | array | NO if text is empty |
| text | Priced item which is not a segment (for example insurance) | string | NO if segment_identifiers is empty |
Account Object
Accounts are identified by the mtrip_account_id, or a combination of office_id and corporate_id.
The attribute mtrip_account_id is a unique identifier generated by mTrip, office_id and corporate_id are optional and provided by you.
| Name | Description | Type | Optional |
|---|---|---|---|
| name | Name of the agency, corporate client, brand or profile | string | YES (will be computed from the date if not present) |
| address | string | YES | |
| city | string | YES | |
| country | string | YES | |
| zip | string | YES | |
| description | string | YES | |
| logo | Dimensions: 400px by 200px (larger images will be resized and cropped)) – Format: .jpg or .png. | string | YES |
| header_pictures | Will be displayed on the main screen header. You can provide one or more pictures. Dimensions: 640px by 340px – Format: .jpg or .png. The logo will be displayed if no header_pictures is provided | array | YES |
| office_id | Agency GDS ID | string | YES |
| corporate_id | string | YES | |
| in_app_messaging_email | Recipient email address for the in-app messaging feature (usually customer service email) | string | YES |
| copy_from_account | Allows to copy the settings and data from an existing account when creating a new one. The hash must contain a combination of keys to identify the account: office_id, corporate_id, mtrip_account_id Account’s attributes will only be copied if a key is empty. |
hash | YES |
| parent | Specify the parent account | hash | YES |
| contacts | List of contacts available | hash | YES |
Inventory Object
Inventory Object is used to send us information on accommodation or activities used regularly across trips.
Using the Inventory Object is optional, please contact us for advise.
| Name | Description | Type | Optional |
|---|---|---|---|
| name | Name of the accommodation or activity | string | NO |
| inventory_id | Unique id used to call the inventory object (activity or accommodation) in the trip | string | NO |
| inventory_type | activity or accommodation | string (value must be activity or accommodation) | NO |
| activity_type | For activity only | [“birthday_reminder”, “car_rental”, “coffee_break”, “concert”, “conference”, “cultural_visit”, “entertainment”, “entrances_fees”, “excursion”, “family_whereabouts”, “guides”, “indoor_exercise”, “meal”, “not_classified”, “outdoor_activity”, “phone_call”, “plane”, “riding_tour”, “ships_andriverboats”, “shopping”, “sightseeing”, “spa”, “sport”, “tennis”, “train”, “transport”, “trekking”, “water_sport”, “working_session”, “workshop”] | YES |
| description | Description of the accommodation or activity displayed to the user | text | YES |
| location | Geo-location of the accommodation or activity | location | YES |
| address | Address of the accommodation or activity | string | YES |
| picture_url | array of all the pictures url (files should be in png or jpeg format) | array | YES |
| city | For accommodation only – Name of the destination to which the accommodation should be attached to. | string | YES |
| phone | For accommodation only – Phone number (recommended format: +[country code] [phone number]) | string | YES |
| For accommodation only – Email address | string | YES |
HTTP Status and Error Codes
We use standard HTTP status 2XX for success and 4XX when something fails.
Specifically, 401 means that your API key is invalid and 422 suggests that the json data that you sent is invalid.
If the request fails, we send a json object containing information about the cause of the failure that can useful for debugging.
Examples
Independent Traveler – Single Traveler
Independent Traveler – Multiple Travelers
Organized Tours
{
“name”: “Your trip to Prague”,
“mtrip_account_id”: 10460,
“trip_type”: “type_4”,
“identifier”: “PFRUEY”,
“start_date”: “2017-10-26T00:00:00+0200”,
“end_date”: “2017-10-30T00:00:00+0100”,
“travelers”: [
{
“email”: “[email protected]“,
“first_name”: “John”,
“last_name”: “Doe”,
“role”: “traveler”,
“language”: “en”,
“phone”: “+1 514 514 5000“,
“send_invitation_type”: 2,
“identifier”: 22574388
}
],
“destinations”: [
{
“name”: “Prague”,
“start_date”: “2017-10-26T00:00:00+0000”,
“end_date”: “2017-10-30T00:00:00+0000”,
“activities”: []
}
],
“transports”: [
{
“transport_type”: “Plane”,
“reservation_reference”: “N16Q8K”,
“airline_iata”: “FR”,
“transport_number”: “2121”,
“departure_date”: “2017-10-26T08:15:00+0200”,
“comments”: “Baggage Allowance: 2 Piece(s)”,
“departure_city”: “Brussel”,
“arrival_city”: “Prague”
},
{
“transport_type”: “train”,
“departure_date”: “2018-11-26T10:13:00+02:00”,
“transport_number”: “9019”,
“reservation_reference”: “UKCTUW”,
“departure_city”: “Paris”,
“arrival_city”: “London”,
“airline_company”: “Eurostar”,
“departure_airport”: “Paris Gare du Nord”,
“arrival_airport”: “London Saint Pancras”,
“arrival_date”: “2018-11-26T11:30:00+01:00”,
“travelers_details”: [
{
“traveler_identifier”: “22574388”,
“class”: “Second class”,
“seat_number”: “Coach 2, seat 21”
}
]
},
{
“transport_type”: “car”,
“airline_company”: “Hertz”,
“comments”: “Unlimited mileage”,
“transport_craft”: “Compact car”,
“departure_address”: “1030 W Manchester Blvd, Inglewood, CA 90301”,
“departure_location”: {
“latitude”: 33.9593275,
“longitude”: -118.3749026
},
“departure_airport”: “Hertz Downtown”,
“departure_city”: “Inglewood”,
“arrival_address”: “3355 Admiral Boland Way, San Diego, CA 92101”,
“arrival_location”: {
“latitude”: 32.7366635,
“longitude”: -117.1805156
},
“arrival_airport”: “San Diego Airport”,
“arrival_city”: “San Diego”,
“departure_date”: “2018-10-06T21:58:24Z”,
“arrival_date”: “2018-10-06T21:58:28Z”,
“reservation_reference”: “LC-95056-5”,
“travelers_details”: [
{
“traveler_identifier”: “22574388”
}
]
},
{
“transport_type”: “Plane”,
“reservation_reference”: “N16Q8K”,
“airline_iata”: “FR”,
“transport_number”: “3970”,
“departure_date”: “2017-10-30T08:55:00+0100”,
“comments”: “Baggage Allowance: 2 Piece(s)rnMeal: Breakfast”,
“departure_city”: “Prague”,
“arrival_city”: “Brussel”
}
],
“accommodations”: [
{
“name”: “Sheraton Prague Charles Square”,
“from_date”: “2014-09-23T18:00:00+00:00”,
“to_date”: “2014-09-26T18:00:00+00:00”,
“location”: {
“latitude”: 50.07745,
“longitude”: 14.422684
},
“address”: “Zitna 561/8”,
“picture_url”: “https://cdn.mtrip.me/user_pictures/85452/8HDfHjd7_70e78642c0700a.jpg“,
“type_of_room”: “Deluxe Room”,
“booking_number”: “102467270”,
“city”: “Prague”,
“phone”: “+420 225 999 999“,
“email”: “[email protected]“
}
]
}
Change Log
| Date | Version | Description |
|---|---|---|
| 05/31/2022 | 3.1 | Add pricing and service objects |
| 08/06/2020 | 3 | API Objects and attributes renaming and new Objects, previous naming can still be used: Guide Object -> Trip Object Introduction of Flight Object, Car Rental Object and Train Object |
| 08/06/2020 | 2.5 | Add trip information document object |
| 03/13/2019 | 2.1 | Add booking status to a trip |
| 09/13/2019 | 2.0 | Add Virtual Credit Cards (Conferma or Troovo) |
| 09/06/2019 | 1.9.9.1 | Add additional attributes to travelers in Transport and Accommodation Objects |
| 06/19/2019 | 1.9.9 | Add user roles |
| 05/22/2019 | 1.9.8 | Add ISO code for destination’s country |
| 05/02/2019 | 1.9.7 | Add cruises |
| 03/28/2019 | 1.9.6 | Add check-in and check-out times for accommodation |
| 01/25/2019 | 1.9.5 | Add LOCODE code |
| 06/13/2018 | 1.9 | Add travelers manager and assistant info for business travelers |
| 05/08/2018 | 1.8 | send_invitation deprecated and replaced by send_invitation_type |
| 11/22/2017 | 1.7 | API Status check method |
| 09/20/2017 | 1.6 | Add trip_type to specify the trip layout |
| 09/01/2017 | 1.5 | Inventory Object and activities per traveler |
| 04/21/2017 | 1.4 | Create and update accounts/agencies/brands |
| 11/30/2016 | 1.3 | Tour Leader status added to travelers |
| 10/27/2016 | 1.2 | Retrieve mobile app encrypted download links. Create an itinerary based on a template |
| 06/06/2016 | 1.1.9 | Specify the class, seat number, ticket number per traveler |
| 06/07/2016 | 1.1.8 | Option to force the order of the itinerary items (transport and destinations) |
| 05/26/2016 | 1.1.7 | Travel documents can be attached to a specific traveler in a trip |
| 01/06/2016 | 1.1.6 | Scheduling of email invitation sending |
| 01/04/2016 | 1.1.5 | Add time for activities |
| 12/17/2015 | 1.1.4 | Add document object |
| 07/20/2015 | 1.1.3 | Add departure_airport_iata and arrival_airport_iata |
| 06/30/2015 | 1.1.2 | Can delete guides |
| 06/23/2015 | 1.1.1 | Add mtrip_account_id comment when testing on sandbox |
| 06/12/2015 | 1.0.0 | Add “phone” and “email” property to accommodation object add picture_url, description and location properties to destination object |
