The TripWorks REST API lets your code read and change your account's data over HTTPS. You create an API key, choose what it can access, and send requests to your own TripWorks address. This article takes you from a new key to a first working request, and explains the rules that apply to every request: access, filtering, paging, errors, and limits.

What can you do with the REST API?

The API is organized by object, such as bookings, customers, and locations, and most objects support the usual create, read, update, and delete operations. TripWorks calls an activity an experience in the API. To see how trips, trip orders, bookings, and customers fit together, read How TripWorks data fits together. Examples of what you can work with:

• Bookings and trips. List and get bookings, add or remove a booking, set a booking's status for one booking or several, mark waivers signed, and read each booking's add-ons, custom fields, products, resources, and waivers. List and get trips, and read the manifest.
• Guests. Create, update, delete, and merge customers. List and manage reviews. Read phone calls and call tags.
• Your catalog. Create and manage experiences (including their waiver configurations), locations, restrictions, waiver types, promo codes, and gift cards (including activating and reloading them).
• Notes and sources. Create and manage trip notes and trip sources.
• Partners. Create and manage resellers.
• Reports and history. Run the Payment Detail and Sales Detail reports, and read the audit log.
• Your team. List and update team member profiles.

The API reference lists every object and operation and is always current, so check it for the full list.

Create an API key

1. In TripWorks, go to Setup Integrations and open the REST API card.
2. On the Keys tab, select Create key.
3. Enter a Name that says what the key is for, such as Internal Reporting or Mobile App.
4. Under Permissions, set each object to None, Read, or Write. Hover the question mark next to an object to see exactly what that level allows.
5. Select Create key, then select Copy when your new key appears.

Each key belongs to one account, so the key itself decides whose data a request can see or change. Give each integration its own key with only the access it needs. That way you can rotate or delete one without breaking the others. See How API keys and access work for how to choose permissions.

Send your first request

Send the key as a bearer token to your account's own address. Every account has its own subdomain, so requests go to https://your-account.tripworks.com.

curl https://your-account.tripworks.com/rest/gift-cards \
  -H "Authorization: Bearer tw_xxxxxxxxxxxxxxxxxxxx"

Every response includes a success boolean. A list response puts its rows under the object's own name (such as gift_cards or locations) next to a meta object with per_page, has_more, and next_cursor.

To try requests without writing code, open the API reference tab on the REST API card. Each object lists its operations, and a playground lets you paste your key as the bearer token and send a real request. A curl button gives you the same request for a terminal. Your developer can also read the public reference at api-docs.tripworks.com, or load the OpenAPI document into their tools.

How do scopes work?

A scope is a permission granted to a key, per object and per direction, such as gift-cards.read and gift-cards.write. You choose them when you create the key, and you can narrow them to exactly what the integration needs.

• A request with no key, or a malformed one, gets a 401.
• A valid key without the right scope for the request gets a 403.
• To change a key's access, open it on the Keys tab and select Save changes.
• To replace a key's token, select Rotate key. Anything still using the old token stops working.
• To remove a key, open it and select Delete key.

How do you filter, sort, and page results?

Filtering. A bare ?field=value means equality. Every other comparison uses brackets, as in ?field[op]=value, with the operators contains, begins_with, gte, and lte. Each field accepts only the operators it declares, and an unsupported one is rejected with a 422. For example, find customers by part of an email address:

GET /rest/customers?email[contains]=jordan

Or list reserved trips from a date onward, newest first:

GET /rest/trips?trip_status=reserved&sale_date[gte]=YYYY-MM-DD&sort=-sale_date

Sorting. Use ?sort=field for ascending or ?sort=-field for descending. Each list accepts only the sort fields it declares, and anything else gets a 422.

Paging. Paging uses a cursor, not page numbers. Set ?per_page=N (each object has its own maximum) and pass ?cursor= with the meta.next_cursor from the previous response. Keep going while meta.has_more is true. A cursor reused with a different sort gets a 422 instead of returning the wrong page.

What do errors look like?

A failed request includes a human-readable message and a structured error object with a stable code. Branch on the code, not on the message text, because the wording can change. See Handle errors and decisions in the REST API for the codes and a worked example.

• 401: no key, or a malformed key.
• 403: the key lacks the scope for this request.
• 409: TripWorks needs a decision before it can finish. See the next section.
• 422: the request was understood but a field, filter, or sort isn't valid. The response lists each field that failed.

What happens when TripWorks needs a decision?

Some actions need a choice that TripWorks can't make for you. Adding guests to a trip that has voucher codes is one example: you decide whether to reapply a voucher or keep the bookings as they are. Instead of guessing, TripWorks stops and asks.

1. Send the request as usual, for example POST /rest/bookings.
2. If a choice is needed, TripWorks replies with 409 and the error code decision_required, with a list of decisions. Each one has a kind and a context that describes the choice.
3. Send the same request again with your answers in decisions, keyed by kind.

For a voucher decision, the answer looks like this. The strategy must be exactly REAPPLY or KEEP_AS_IS, and tripVoucherCodeId must be a voucher code on that trip.

{
  "decisions": {
    "voucher_reapply": { "strategy": "REAPPLY", "tripVoucherCodeId": 42 }
  }
}

Nothing is saved until every decision is answered. An answer that isn't recognized is refused with a 422 before anything is created. Add "dry_run": true to run every check, including capacity and your answers, without saving anything.

What are the rate limits?

Limits stop runaway code from flooding the system. If you hit one, your code usually needs to fetch less often, for example by not checking every few seconds.

• Reads: 200 requests a minute and 3,000 an hour, per key.
• Writes: 65 requests a minute and 1,000 an hour, per key.
• All keys on one account: 400 requests a minute together.

A request over a limit is rejected with a 429. The Limits tab on the REST API card shows each key's usage against these numbers, and the Logs tab lists your API calls and security events. To learn about changes instead of checking for them, use webhooks. For habits that keep an integration fast, see Build integrations that stay fast and efficient, and to review requests, see Monitor and troubleshoot API activity.

Examples

• Find a guest by email. Send GET /rest/customers?email[contains]=jordan and read the matching customers.
• List this month's reserved trips. Send GET /rest/trips with trip_status=reserved and a sale_date[gte] filter, sorted with sort=-sale_date.
• Find bookings with unsigned waivers. Send GET /rest/bookings?booking_waiver_status=unsigned.
• Mark a guest's waivers signed after they sign on paper. Send POST /rest/bookings/{id}/mark-waivers-signed.
• Issue a gift card from your own checkout. Send POST /rest/gift-cards, then POST /rest/gift-cards/{id}/activate.
• Leave a note on a trip. Send POST /rest/trip-notes so the note appears for your team.
• Preview a booking before you create it. Send POST /rest/bookings with dry_run set to true and read the checks that would run.

Frequently asked questions

Related

• Does TripWorks have an API?
• How TripWorks data fits together
• How API keys and access work
• Monitor and troubleshoot API activity
• Handle errors and decisions in the REST API
• Build integrations that stay fast and efficient
• Set up webhooks
• Connect TripWorks to your AI assistant (MCP)
• Set up your Zapier integration
• Permission groups