---
title: "Integrate WaW into your platform"
description: "Build a connection that sends your customers' bookings and contacts to their WaW account."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.withoutaworry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate WaW into your platform

This guide is for platforms whose customers also work in WaW. Your platform sends new and changed bookings to the customer's WaW account, so they never type the same booking twice.

## How it fits together

1. A customer of yours has a WaW account.
2. The customer approves your platform. WaW gives you a customer key for that account.
3. You store the key with that customer in your platform.
4. Each time a booking or contact changes on your side, you send the change to WaW with that key.

## Step 1: connect a customer

Do this once for each customer.

1. **The customer has a WaW account** with an active subscription or trial.
2. **The customer approves the connection.** Contact WaW to start this. An admin of the customer's WaW team has to approve it.
3. **WaW sends you a customer key** through a secure channel. One key belongs to one customer and one environment.
4. **You store the key on your server**, linked to that customer. Use a secret store or an encrypted column. Never put a key in a browser, a mobile app, a URL or a log.

A key only opens that one customer's account. You cannot use it to write to another customer. See [Authentication](/partners-api/authentication).

## Step 2: decide when to send what

Most integrations need four moments:

| What happens on your platform | What you send to WaW |
| --- | --- |
| A new client is added | [Create a contact](/partners-api/contacts#create-a-contact) |
| A new booking is made | [Create a booking](/partners-api/bookings#create-a-booking), with the WaW contact ID as `contact_id` |
| A booking or client changes | [Update a booking](/partners-api/bookings#update-a-booking) or [Update a contact](/partners-api/contacts#update-a-contact), with only the changed fields |
| A booking is cancelled | Update the booking to `status: "lost"` with a `lost_reason` |

Always create the contact before the booking. The booking needs the contact's WaW ID.

The API cannot delete records. A cancelled booking stays in WaW with the status `lost`, so the customer keeps the history.

## Step 3: keep track of IDs

Every record has two IDs:

| ID | Who chooses it | What it is for |
| --- | --- | --- |
| `external_id` | You | Your own ID, such as your booking number. Send it when you create a record. |
| `id` | WaW | Returned when you create a record. Use it in the URL to update that record. |

Store the WaW `id` next to your own record. A simple mapping table works well:

| Your record | Customer | WaW `id` |
| --- | --- | --- |
| Booking 8421 | Venue A | `3f1e9a2b-…` |
| Client 551 | Venue A | `7b0c2f4e-…` |

Retries are safe. If a create request times out, send the same request again. WaW recognises your `external_id` and returns the record it already made, so you never get a duplicate. See [Retries](/partners-api/errors-and-limits#retries).

## Step 4: map your data to WaW

**Statuses.** WaW has three statuses: `draft`, `confirmed` and `lost`. Map each status on your platform to one of them, for example:

| Your status | WaW status |
| --- | --- |
| Request, option or proposal | `draft` |
| Booked | `confirmed` |
| Cancelled or declined | `lost`, with a reason |

**Dates.** Send dates with a time and a timezone offset, for example `2027-06-12T16:00:00+02:00`. A date without a time, or a time without an offset, is refused.

**Location.** `location` is required on a booking. For a venue, this is usually the venue's name or address, or the room.

**Contacts.** Send `first_name` and `last_name` for people. Send `name` with `entity_type: "company"` for companies.

## Step 5: test, then go live

1. **Test on acceptance.** Use `https://acc-api.withoutaworry.com` with a test key from WaW. Create, update and cancel a few bookings and check them in the WaW test account.
2. **Go live.** Switch to `https://api.withoutaworry.com` and the customer's production key.

Acceptance keys do not work on production, and production keys do not work on acceptance.

## Good to know

- **Rate limit.** Each customer key allows 60 requests per minute. If you get `429`, wait for the seconds in the `Retry-After` header. Queue your requests per customer.
- **Last update wins.** If the customer edits a field in WaW and you update the same field later, your value replaces theirs.
- **When a key stops working.** A `403` means the customer's subscription ended or the connection was revoked. Pause the sync for that customer and contact WaW.
- **Getting help.** Every error includes a `request_id`. Send it to WaW when something fails.

## Checklist

- [ ] Keys are stored per customer, on the server only.
- [ ] Contacts are created before bookings.
- [ ] Your own ID goes in `external_id`; the WaW `id` is stored next to your record.
- [ ] Statuses are mapped; cancellations become `lost` with a reason.
- [ ] Dates include a time and a timezone offset.
- [ ] `429` and `5xx` responses are retried with a delay.
- [ ] Everything was tested on acceptance first.

Source: https://docs.withoutaworry.com/partners-api/integrate/index.mdx
