TripIt API Documentation - v1 - Notification API

Index

• Overview
• API Endpoints

Overview

The TripIt Notification API allows a developer to receive a push notification from TripIt when a change occurs in a user's trips. By registering to receive such notifications and by implementing an HTTPS listener endpoint, the developer will receive the identity of the object that has changed so that he can retrieve the updated object and keep his system up to date with TripIt.

Subscribing to and unsubscribing from a user's trip changes is done with API calls that follow the same authentication and logical patterns as the other TripIt API endpoints. Every such request must be authenticated with OAuth in order to authorize the developer, and also to identify the user for which subscriptions are made.

API Endpoints

Subscribe

In order to subscribe to notification events for a user, call the "/v1/subscribe" endpoint in the TripIt API. The "subscribe" endpoint takes a single required parameter called "type". Currently, the only valid value for the "type" parameter is "trip".

So as an example, in order to subscribe to a specific user's trip notification events, simply call, with the necessary OAuth authentication credentials, "/v1/subscribe?type=trip".

Unsubscribe

In order to unsubscribe from a user's notification events, call the "/v1/unsubscribe" endpoint in the TripIt API. The "unsubscribe" endpoint takes an optional parameter called "type". If specified, it indicates the type of notification from which to unsubscribe. If not specified, all notification subscriptions for the user are removed.

Callback URL

Currently, notifications may be subscribed to for changes to trip objects.

When a change is made to a trip to which you are subscribed, TripIt will make a corresponding HTTP request to your server on a URL that you provide in the following manner: on the first edit/delete on a trip or any of its trip items, a notification will be sent to your callback url. However, on subsequent changes to that trip for the immediate next 10 minutes, notifications are suppressed -- this is to prevent any flood of callbacks that may hit your server due to a large number of changes to a trip.

In order to provide the URL to TripIt, contact api-support@tripit.com. Please include the application name, email address used to register the application, and the desired callback URL in the email.

The callback URL must use SSL/TLS (it must be an HTTPS URL) and it may not contain ? or &. It also must not redirect. Upon successful receipt of a notification it must return HTTP 200.

The callback URL is called with the following HTTP POST parameters:

• type - The type of the object that was changed. Currently, this is always "trip". In the future additional types may be available, so this parameter should be checked.
• id - The TripIt ID of the object that was changed. If the object is a trip, for example, this ID may be used with the API to fetch the trip details.
• change - The type of change made to the object that was changed. The valid change types are "created", "updated", "merged", "deleted", "plans_created", "plans_updated", "plans_deleted", "plans_moved", "plans_copied", "comment_created", "comment_deleted", and "invitations_created".
• oauth_token_key - One or more of these parameters will be included. Each is the OAuth token key of one user for whom you are subscribed for this specific change notification.