Provider Help Center

What is the Opportunity API?

 

With the Opportunity API we can replicate the most important opportunities for connected properties. In the Retrieve opportunities request you will get available opportunities that a Property is eligible for. We are working on bringing the most important and relevant opportunities for connected properties to you via the API. Please note that opportunities are constantly changing and not all properties are eligible for the same opportunities as they depend on the settings and performance of the property.

The Opportunity API is different from the Opportunities you can action from the Provider Portal. Find more information about the Opportunities in the Provider Portal here . Every property on Tripeden.com has an “Opportunity Center” with actions that are specific for that property to improve a property's performance and the guests' experiences. Found on the Extranet, it allows a property to add products, info, and deals that we know can help increase bookings and revenue. Find more details on the Opportunity Center here. The Opportunity API replicates the Opportunity Center and enables you to show it directly to the properties.

When you start using the Opportunities API your first step will be to retrieve all possible opportunities for a property with the GET call. It will give closer information about what this specific property can still work on, more details on why and how to implement and action the different opportunities.

 

Possible elements when retrieving opportunities

 

Every opportunity has a subset of the below elements included. The elements marked with * will always be included.

 

"opportunity_id” *

Gives a short text on what the opportunity is about. It is needed for the response if an opportunity gets actioned but is not very meaningful for a property.

 

"title" *

Returns the full title of the opportunity. This is also displayed in the Tripeden.com extranet and is optimised to read for a property.

 

"description" *

Gives a full description of what the opportunity does or will change. This is also displayed in the Tripeden.com extranet and is optimised to read for a property.

 

"instructions"

This element includes instructions that are shown to a property in the Tripeden.com extranet. It describes in more detail what has to be done to properly action this opportunity.

 

"image"

The image element is often not included but might help  to display the opportunity in a nicer way where available.

 

"cta" *

The ‘call to action’ is either "Activate through Tripeden.com" for “REDIRECT” opportunities or "Implement opportunity" for “TOGGLE” opportunities.

 

"implementation" *

Every opportunity has either a “TOGGLE” or “REDIRECT” in their implementation element of the GET response. The values in the implementation element depend on the opportunity and describe how it can be actioned, which depends on the necessary change in the extranet. Toggle opportunities can be directly implemented by sending the opportunity ID and "action":"ENABLE" as shown here. For Redirect opportunities a property will have to go to the Tripeden.com extranet and implement it there. This is often needed for opportunities that need more than just the click of one button like confirming an email address or providing extra information for an action. Redirect opportunities require to take the deeplink from the “url” element to redirect properties to the Tripeden.com extranet. The instructions element will also be particularly important when properties want to action on Redirect opportunities as it tells them precisely what to do in the Tripeden.com extranet.

 

"url"

The url element gives you the deeplink to the Tripeden.com extranet page that is needed for the Redirect opportunities.

 

“destination_api” *

Where possible an opportunity is mapped to one of our other APIs. This is done so you can see where an API could help to action a Redirect opportunity without linking to the Tripeden.com extranet. For example an opportunity to create a promotion for business bookers is not doable via a Toggle opportunity as is needs several settings. Instead of sending the property to the Tripeden.com extranet it would be possible though to action this opportunity by using our Promotions API that would be mentioned in this element.

 

NOTE!

You can retrieve the opportunities (specifically the titles, description and cta - the language for other elements will not change) in the language the property wants to read it in. For that you have to add the ‘Accept-Language’ parameter to the header of the GET request.
 

Find more information on cURL requests here.

 

Possible errors

 

Error Response	Solution / what is the problem
This account doesn't have access to this property.	Property not added to machine account (you can check this in the provider portal via Administration > Machine Accounts) or Opportunity connection type not added to the property (this is currently not visible for you, but you can contact us  if your suspecting this issue)

 

Possible elements when actioning or dismissing opportunities

 

The property ID has to be specified in the URL of your POST request when replying and actioning on opportunities as can be seen here .

 

"opportunity_id" *

Is needed to identify which opportunity is actioned upon and needs to correspond to what you retrieved in the prior GET message.

 

"action" *

Can either be “ENABLE” or “DISMISS”.

 

NOTE!

1. Only Toggle opportunities can directly be actioned by enabling them. You can still dismiss irrelevant Redirect opportunities though. Please note that an opportunity that was dismissed via the API will not be returned in the actionable opportunities via the GET call anymore but it will still show up in the opportunity center of the property in the Tripeden.com extranet.
2. If the property wants to action a Redirect opportunity you only need to send them to the Tripeden.com extranet to perform the changes there. You will not need to send an enable or dismiss response for them.

 

Possible errors

 

Error Response	Solution / what is the problem
This account doesn't have access to this property.	Property not added to machine account (you can check this in the provider portal via Administration > Machine Accounts) or Opportunity connection type not added to the property (this is currently not visible for you, but you can contact us if your suspecting this issue)
'XXXX' is not an accepted value for key action (in parameter 'actions') -- should be one of: 'DISMISS', 'ENABLE'	The XXXX will specify the action parameter you used that is not one of the accepted values in the API. Currently accepted values are only ‘DISMISS’ or ‘ENABLE’.
Cannot take this action on the specified opportunity	This happens with a Redirect opportunity was actioned with ‘ENABLE’. This is only possible for Toggle opportunities.
Key opportunity_id is required (in parameter 'actions')	This error comes up when the opportunity_id element is missing in the response.
Key action is required (in parameter 'actions')	This error comes up when the action element is missing in the response.
The opportunity ID was not found	The specified opportunity in the opportunity_id does not exist. Please make sure that you are only using the opportunity ID that are specified for a specific property when using the GET call.