How-to: Use 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

Available on: ENTERPRISE plans only

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.

Note: 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”]}

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: 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.


Need more help? 

Reach out to the YouLi support team via a chat box at the bottom of your screen or submit a ticket request. If you need more advanced support, schedule a 1:1 Consulting session with one of our experts, as we will walk you through the features and best practices.