Back to home

Help Center

HOW-TO

How-to: Use The Create Trip API To Automate Integration With Your CRM

For larger teams with a CRM sales funnel in place, createtrip API allows for creation and update of a trip in YouLi which can be used for quoting clients

INCLUDED PLANS: This is only available on Enterprise plans

Create Trip API - CRM Integration

Released 2021:

CreateTrip API Released in 2021 - read release notes

Authentication

The current method of authentication is username and password with a Bearer Token
- https://youlivetotravel.github.io/youli-doco/#authentication
Requests that require authentication will return 401 Not Authorized if the user has not authenticated.

API Reference Documentation

Create or update Trip

Creates a new Trip or updates an existing Trip if a valid trip ID is provided.

CAUTION: If the Trip ID is provided, then ALL values stored in Dynamics must be passed or they will be assumed to be blank and cleared/set to blank/NULL. Do not just send what has been changed.

Resource Information

Method	Purpose
Response formats	JSON
Requires authentication?	Yes
Rate limited?	Yes
Requests	15/minute

Request

Method

URL

POST

https://youli.io/api/trip/createtrip

Parameters

CAUTION: Automated Payment Reminders will only be enabled if Due Dates are set.

Even if set, reminders are not sent until the contact accepts the quote by changing their Registration Status from "Invited" to "Registered" (by clicking the button on the Trip Page).

Name	Type	Description	Required	Example
id	GUID	Unique Identifier for Trip generated by YouLi	No blank => create valid => update	bb29564e-86dd-e811-81ad-0638e1369576
templateId	GUID	Unique Identifier for a Template created in YouLi. This will be ignored if an existing trip Id has been provided.	No	b77246b2-a0ab-eb11-a7ad-0003ffedcb08
isPublic	Boolean (true/false)	Flag to set visibility of trip	No, defaults to false	N/A
realignDates	Boolean (true/false)	Flag to align other trip dates if new startDate provided.	No, defaults to true	true
alias	String(256)	Must be unique for the authenticated trip owner. Must only contain letters, numbers and hyphens.	Yes	tr2345678
name	String(80)	Does not have to be unique – but recommended for UX	Yes	Manchester Uni Winter Study Trip
mainContactEmail	String	Email address of the Main Contact for this Trip – must be Team Owner or Team Member in authenticated account or	Yes	mandy@yourteamdomain.com
overviewTitle	String	See below	No	Manchester University
tripTimeZone	String	Valid time zone in IANA or Windows format	Yes
startDate	date in ISO8601, no time zone	Date trip starts in time zone of trip Required if End Date is provided.	No	2021-04-01T00:00:00
endDate	date in ISO8601, no time zone	Date trip ends in time zone of trip. Must be after start date. Required if Start Date is provided.	No	2021-04-21T00:00:00
primaryLocation	String(256)	Primary location of the trip. Other locations to be set on itinerary items. Used to center the map.	No	Arusha, Tanzania OR Sacramento, California, United States
currency	String(3)	3 char currency code	No	GBP
depositDueDate	date in ISO8601, no timezone	Date when deposit is due in time zone of trip – if set, automated reminders will be ON by default	No	2021-02-21T00:00:00
depositAmountPerPerson	decimal	Amount to be paid for deposit. Warning: this can be set to more than the traveler owes.	No	340
totalAmountPerPerson	decimal	Price per person used for the standard package. Can be amount for whole group if only one person added.	No, unless a depositAmountPerPerson is provided	3040
balanceDueDate	date in ISO8601, no time zone	Date when balance is due in time zone of trip - if set, automated reminders will be ON by default	No	2021-06-21T00:00:00
primaryTravelerFirstName	String(100)	Add person to trip as invited traveler	No, unless primaryTravelerEmail is provided	Robin
primaryTravelerLastName	String(100)	Add person to trip as invited traveler	No	Kerr
primaryTravelerEmail	String(256)	Add person to trip as invited traveler	No, unless primaryTravelerFirstname is provided	bb@manchester.edu.uk
isPublic	Boolean (true/false)	Flag to set visibility of trip	No, defaults to false	true
requiredGroupSize	number	Set the “required group size” parameter for the pricing package. This will automatically add placeholders for this many people on the booking for the primary traveler and add them to their invitation group. Max value is 50.	No
numTravelers	Number	Set the number of travelers for the pricing package. If no totalAmountPerPerson has been provided on creation of a new trip, this parameter will be ignored.	No	32
overview	string	Overview of trip is shown on highlights of Trip Page. Pass \n for new lines to be replaced by YouLi with <br>	No, can be blank	Departing from Manchester, United Kingdom Number of paying passengers: 32 (30 students, 2 teachers) Number of free spots: 1 Deposit per person: 340 Total per person: 3040

NOTE: If the Trip Time Zone is not set to match the Primary Time Zone provided, the Team Member will need to ensure the correct time zone is set in YouLi when editing the time zone. Itinerary-specific time zones must be set on the Itinerary Item objects for flights and other items that occur in a different time zone than the primary location.

Create Trip – special handling

The following is done as part of the Create case:

If totalAmountPerPerson and/or depositAmountPerPerson set:
1. Add new trip cost instalment labeled “Deposit” with depositDueDate
2. Add new trip cost instalment labeled “Balance Due” with balanceDueDate

A standard package labeled “Standard Package” is added with:
1. price per person of totalAmountPerPerson
2. number of travelers set to numTravelers

TRIP is set to BOOKINGS MODE

TIP: Number of Travelers per package can be changed in YouLi UI after this API call made successfully. Otherwise this feature is not visible through the standard Package UI

Update Trip – special handling

If depositAmountPerPerson provided:
- If a matching instalment is found labeled "Deposit"
  - Update found instalment with depositDueDate and depositAmount
- Else:
  - Create a new trip cost instalment labeled “Deposit” and set the depositDueDate and depositAmount
If totalAmountPerPerson provided:
- If there is a single package:
  - Update the price per person to totalAmountPerPerson for the Pricing Package found on the trip
- Else:
  - Create a new package and set the price per person to totalAmountPerPerson

Warning returned if more than one pricing package (trip update will still be completed)

Authorization

The account on YouLi used to Authenticate must have permission to run this API under an Enterprise license.

Requires the advancedAPIEnabled permission

Response

If successful, this method returns a response body with the following structure:

Name	Type	Description
Total	Number	A number representing the number of results (always 1)
Results	Data	Data containing information about the created trip

The Results data will have the following structure:

Name	Type	Description
Id	GUID	GUID of the recently created or updated trip
plannerUrl	string	URL for planners to access and edit trip in YouLi (requires authentication) defaults to /EditSchedule
primaryMagicLink	string	Magic link for the primary traveler if provided
publicLink	string	Public share link for the trip if public (N/A for this integration since they will all be private)

Sample Response

If successful, returns the HTTP status of 200 and a transaction object.

{

    "Total":1,
    "Results": {
        "Id": "341e71a2-489f-e711-8305-985fd3437709",
        "plannerUrl": "https://youli.io/Planner/PlannerEdit/341e71a2-489f-e711-8305-985fd3437709",
        "primaryMagicLink": "http://youli.io/t/sample/sample-trip/06826297-91eb-4e37-806b-70c1a08f657b",
        "publicShareLink": "http://youli.io/t/sample/sample-trip"
    }
}

Status Codes

Status	Response
200	See above for sample response
200	{"warnings" : ["Could not update TotalAmountPerPerson because there are too many packages"]}
200	{"warnings" : ["Could not update MinTravelers because there are too many packages"]}
200	{"warnings" : ["Could not update MinTravelers because no TotalPricePerPerson has been provided"]}
200	{"warnings" : ["Could not update NumTravelers because there are too many packages"]}
200	{"warnings" : ["Could not update NumTravelers because no TotalPricePerPerson has been provided"]}
400	{“errors”: [“Please provide a valid templateId, set to null or omit. Empty string not valid”]}
400	{"errors" : ["Please provide a unique alias”]} See troubleshooting below
400	{"errors" : ["Alias must only contain letters, numbers and hyphens”]}
400	{"errors" : ["Please provide a valid time zone”]}
400	{"errors" : ["Please provide a valid planner email address for the mainContactEmail”]}
400	{"errors" : ["If End Date is provided, Start Date must be provided as well"]}
400	{"errors" : ["If Start Date is provided, End Date must be provided as well"]}
400	{“errors”: [“End Date must be greater than Start Date”]}
400	{"errors" : ["Please provide a valid tripId, set to null or omit. Empty string not valid"]}
400	{“errors” : [“If DepositDueDate is provided, DepositAmountPerPerson must be provided as well”]}
400	{“errors” : [“If DepositAmountPerPerson is provided, TotalAmountPerPerson must be provided as well”]}
400	{“errors” : [“If adding a primary traveler, please provide both PrimaryTravelerFirstName and PrimaryTravelerEmail fields”]}
400	{“errors” : [“RequiredGroupSize must be between 0 and 50 inclusive”]}
400	In general, all validation errors will include a relevant error message
401	{"message" : "Authorization has been denied for this request."}
500	Response will be an error page (HTML)

Troubleshooting

ERROR: Please provide unique alias

If you receive an email alert like this:

This means that the value that was passed in the alias parameter is not unique - so the trip cannot be created.

To resolve this, there are a few options:

Change the alias parameter value to a unique string
1. In this case, change from TR005654 to another value in the CRM before trying the call again
OR: Find the existing trip by searching for TR005654 on the Trip Dashboard
1. Click to Edit the matching Trip
2. Change the TRIP SHORT NAME to something else so a new trip can be created with this alias via API
OR: Contact your development team to find out why the call was made with a duplicate alias instead of with the correct 'id' parameter to indicate that this is an update request. The 'id' for the created trip is returned the first time the trip was created with this alias, so any later calls should use that 'id' to reference it.

ERROR: 400 Bad Request

If your JSON is valid and you still get a Bad Request response, be sure to check that the Main Contact email address is a valid YouLi Planner in your team.
If your email address in your CRM is not the same as the one in YouLi, then your push to YouLi will fail.

Why is my Trip not being returned, even though the Trip Start Date is in the future?

Even if your TRIP START DATE is in the future, if that TRIP has a REGISTRATION CLOSE DATE set to a date in the past, it will not be listed or returned in any API responses.
So, if you still want that Trip to be returned, you should remove the Registration Close Date.

Need more help?

For more tips on pre-trip customer support join the YouLi community of travel professionals with monthly LIVE webinars and Q&A sessions.