# Waivers & Surveys (/developers/waivers-and-surveys)



<Callout type="warn">
  The waiver API surface is under active development and may change. The endpoints and types documented here reflect the current implementation but are subject to breaking changes in future releases.
</Callout>

Waivers [#waivers]

Waivers allow operators to collect digital signatures and liability agreements from guests before their booking. The flow is: load the waiver form, look up the reservation, then submit the signed waiver.

getWaiver [#getwaiver]

Retrieve a waiver form definition by location and waiver ID.

```javascript
const result = await api.waiver.getWaiver('location-uuid', 'waiver-id');

if (result.success) {
  const waiver = result.waiver;
  console.log('Waiver:', waiver.name);
  console.log('Fields:', waiver.fields);
  console.log('Requires booking:', waiver.requiresBooking);
}
```

**Parameters**

| Parameter      | Type     | Required | Description   |
| -------------- | -------- | -------- | ------------- |
| `locationUuid` | `string` | Yes      | Location UUID |
| `waiverId`     | `string` | Yes      | Waiver ID     |

GetWaiverResponse [#getwaiverresponse]

| Field     | Type      | Description                   |
| --------- | --------- | ----------------------------- |
| `success` | `boolean` | Whether the request succeeded |
| `waiver`  | `Waiver`  | Waiver form definition        |

Waiver [#waiver]

| Field             | Type          | Description                                             |
| ----------------- | ------------- | ------------------------------------------------------- |
| `id`              | `string`      | Waiver identifier                                       |
| `name`            | `string`      | Waiver title                                            |
| `fields`          | `any`         | Form field definitions (structure varies by waiver)     |
| `contactEmail`    | `string`      | Operator contact email                                  |
| `logoUri`         | `string`      | Company logo URL                                        |
| `appendLogo`      | `boolean`     | Whether to display the logo                             |
| `requiresBooking` | `boolean`     | Whether a reservation lookup is required before signing |
| `theme`           | `WaiverTheme` | UI theme colors                                         |

WaiverTheme [#waivertheme]

| Field        | Type     | Description           |
| ------------ | -------- | --------------------- |
| `primary`    | `string` | Primary color         |
| `secondary`  | `string` | Secondary color       |
| `accent`     | `string` | Accent color          |
| `background` | `string` | Background color      |
| `paper`      | `string` | Card/paper background |
| `text`       | `string` | Text color            |
| `textMuted`  | `string` | Muted text color      |
| `border`     | `string` | Border color          |
| `error`      | `string` | Error state color     |
| `success`    | `string` | Success state color   |
| `warning`    | `string` | Warning state color   |

***

getReservation [#getreservation]

Look up a reservation so the guest can attach a waiver to their booking. The guest typically provides their confirmation number.

```javascript
const result = await api.waiver.getReservation({
  lid: 'location-uuid',
  wid: 'waiver-id',
  type: 'confirmation',
  value: 'ABC123'
});

if (result.success) {
  console.log('Reservation found:', result.confirmationNumber);
  console.log('Customer:', result.customerName);
  console.log('Date:', result.date);
}
```

GetReservationRequest [#getreservationrequest]

| Field   | Type     | Required | Description                              |
| ------- | -------- | -------- | ---------------------------------------- |
| `lid`   | `string` | Yes      | Location UUID                            |
| `wid`   | `string` | Yes      | Waiver ID                                |
| `type`  | `string` | No       | Lookup type (e.g., `"confirmation"`)     |
| `value` | `string` | No       | Lookup value (e.g., confirmation number) |

GetReservationResponse [#getreservationresponse]

| Field                | Type      | Description                  |
| -------------------- | --------- | ---------------------------- |
| `success`            | `boolean` | Whether the lookup succeeded |
| `id`                 | `string`  | Reservation ID               |
| `date`               | `string`  | Booking date                 |
| `customerName`       | `string`  | Customer name                |
| `customerEmail`      | `string`  | Customer email               |
| `customerPhone`      | `string`  | Customer phone               |
| `status`             | `string`  | Reservation status           |
| `confirmationNumber` | `string`  | Confirmation number          |

***

submitWaiver [#submitwaiver]

Submit a completed waiver with all filled-in fields, a timestamp, and an integrity hash.

```javascript
const result = await api.waiver.submitWaiver({
  waiverId: 'waiver-id',
  locationId: 'location-uuid',
  waiverName: 'Liability Waiver',
  reservationId: 'reservation-id',
  reservationConfirmationNumber: 'ABC123',
  fields: [
    { fieldId: 'full_name', value: 'Jane Smith' },
    { fieldId: 'signature', value: 'data:image/png;base64,...' },
    { fieldId: 'agreed', value: true }
  ],
  submittedAt: new Date().toISOString(),
  dataHash: 'sha256-hash-of-field-data',
  bfp: 'browser-fingerprint'
});

if (result.success) {
  console.log('Waiver submitted:', result.submissionId);
  console.log('Confirmation:', result.confirmationNumber);
}
```

SubmitWaiverRequest [#submitwaiverrequest]

| Field                           | Type     | Required | Description                              |
| ------------------------------- | -------- | -------- | ---------------------------------------- |
| `waiverId`                      | `string` | Yes      | Waiver ID                                |
| `locationId`                    | `string` | Yes      | Location UUID                            |
| `waiverName`                    | `string` | No       | Waiver name                              |
| `reservationId`                 | `string` | Yes      | Reservation ID from `getReservation`     |
| `reservationConfirmationNumber` | `string` | Yes      | Confirmation number                      |
| `fields`                        | `any[]`  | Yes      | Completed form fields                    |
| `submittedAt`                   | `string` | Yes      | ISO timestamp of submission              |
| `dataHash`                      | `string` | Yes      | SHA-256 hash of field data for integrity |
| `bfp`                           | `string` | Yes      | Browser fingerprint for fraud prevention |

SubmitWaiverResponse [#submitwaiverresponse]

| Field                | Type      | Description                     |
| -------------------- | --------- | ------------------------------- |
| `success`            | `boolean` | Whether submission succeeded    |
| `submissionId`       | `string`  | Unique submission ID            |
| `submittedAt`        | `Date`    | Server-recorded submission time |
| `confirmationNumber` | `string`  | Waiver confirmation number      |

***

Full Waiver Example [#full-waiver-example]

```javascript
const api = new ResytechApi();
await api.initialization.initialize({ identifier: 'waiver-session' });

const locationUuid = 'location-uuid';
const waiverId = 'waiver-id';

// 1. Load the waiver form
const waiverResult = await api.waiver.getWaiver(locationUuid, waiverId);

if (!waiverResult.success) {
  console.error('Failed to load waiver:', waiverResult.message);
  return;
}

const waiver = waiverResult.waiver;
console.log('Rendering waiver:', waiver.name);
// Render waiver.fields to your UI...

// 2. Look up reservation (if required)
if (waiver.requiresBooking) {
  const reservation = await api.waiver.getReservation({
    lid: locationUuid,
    wid: waiverId,
    type: 'confirmation',
    value: 'ABC123' // from user input
  });

  if (!reservation.success) {
    console.error('Reservation not found');
    return;
  }

  console.log('Found reservation for:', reservation.customerName);

  // 3. Submit the signed waiver
  const fieldData = [
    { fieldId: 'full_name', value: 'Jane Smith' },
    { fieldId: 'signature', value: 'base64-signature-data' },
    { fieldId: 'agreed', value: true }
  ];

  const submission = await api.waiver.submitWaiver({
    waiverId: waiverId,
    locationId: locationUuid,
    waiverName: waiver.name,
    reservationId: reservation.id,
    reservationConfirmationNumber: reservation.confirmationNumber,
    fields: fieldData,
    submittedAt: new Date().toISOString(),
    dataHash: await computeSha256(JSON.stringify(fieldData)),
    bfp: getBrowserFingerprint()
  });

  if (submission.success) {
    console.log('Waiver signed! Confirmation:', submission.confirmationNumber);
  }
}
```

***

Surveys [#surveys]

Post-booking surveys let operators collect feedback. Surveys are accessed via a unique token sent to the customer (typically via email).

getSurvey [#getsurvey]

Retrieve a survey by its access token. The response includes the survey definition, booking context, and operator branding.

```javascript
const result = await api.survey.getSurvey('survey-token-from-email');

if (result.success) {
  const survey = result.survey;
  console.log('Survey:', survey.name);
  console.log('Questions:', survey.questions.length);

  // Booking context for personalization
  const ctx = result.bookingContext;
  console.log(`Hi ${ctx.customerName}, how was your ${ctx.bookingDate} trip?`);

  // Operator branding for styling
  console.log('Logo:', result.branding.logoUrl);
}
```

**Parameters**

| Parameter | Type     | Required | Description                                     |
| --------- | -------- | -------- | ----------------------------------------------- |
| `token`   | `string` | Yes      | Survey access token (URL-encoded automatically) |

GetPublicSurveyResponse [#getpublicsurveyresponse]

| Field            | Type                   | Description                   |
| ---------------- | ---------------------- | ----------------------------- |
| `success`        | `boolean`              | Whether the request succeeded |
| `survey`         | `PublicSurvey`         | Survey definition             |
| `bookingContext` | `PublicBookingContext` | Customer and booking info     |
| `branding`       | `Branding`             | Operator branding and colors  |

PublicSurvey [#publicsurvey]

| Field             | Type               | Description                    |
| ----------------- | ------------------ | ------------------------------ |
| `id`              | `string`           | Survey identifier              |
| `name`            | `string`           | Survey title                   |
| `description`     | `string`           | Survey description             |
| `questions`       | `SurveyQuestion[]` | List of questions              |
| `thankYouMessage` | `string`           | Message shown after submission |

SurveyQuestion [#surveyquestion]

| Field      | Type                     | Description                                            |
| ---------- | ------------------------ | ------------------------------------------------------ |
| `id`       | `string`                 | Question identifier                                    |
| `type`     | `string`                 | Question type (e.g., `"rating"`, `"text"`, `"select"`) |
| `label`    | `string`                 | Question text                                          |
| `required` | `boolean`                | Whether an answer is required                          |
| `order`    | `number`                 | Display order                                          |
| `maxStars` | `number`                 | Maximum stars (for rating questions)                   |
| `options`  | `SurveyQuestionOption[]` | Answer options (for select/choice questions)           |

SurveyQuestionOption [#surveyquestionoption]

| Field   | Type     | Description       |
| ------- | -------- | ----------------- |
| `id`    | `string` | Option identifier |
| `label` | `string` | Option text       |
| `order` | `number` | Display order     |

PublicBookingContext [#publicbookingcontext]

| Field              | Type     | Description               |
| ------------------ | -------- | ------------------------- |
| `customerName`     | `string` | Customer name             |
| `customerEmail`    | `string` | Customer email            |
| `confirmationCode` | `string` | Booking confirmation code |
| `bookingDate`      | `string` | Booking date              |

Branding [#branding]

| Field                 | Type     | Description         |
| --------------------- | -------- | ------------------- |
| `companyName`         | `string` | Company name        |
| `logoUrl`             | `string` | Logo image URL      |
| `locationName`        | `string` | Location name       |
| `primaryColor`        | `string` | Primary brand color |
| `secondaryColor`      | `string` | Secondary color     |
| `accentColor`         | `string` | Accent color        |
| `backgroundColor`     | `string` | Background color    |
| `cardBackgroundColor` | `string` | Card background     |
| `cardTextColor`       | `string` | Card text color     |
| `headerTextColor`     | `string` | Header text color   |

***

submitSurvey [#submitsurvey]

Submit the customer's survey responses.

```javascript
const result = await api.survey.submitSurvey({
  token: 'survey-token-from-email',
  name: 'Jane Smith',
  email: 'jane@example.com',
  responses: {
    'question-id-1': 5,          // star rating
    'question-id-2': 'Great!',   // text response
    'question-id-3': 'option-a'  // select response
  }
});

if (result.success) {
  console.log(result.thankYouMessage);
}
```

SubmitSurveyRequest [#submitsurveyrequest]

| Field       | Type                  | Required | Description                        |
| ----------- | --------------------- | -------- | ---------------------------------- |
| `token`     | `string`              | No       | Survey access token                |
| `responses` | `Record<string, any>` | No       | Map of question ID to answer value |
| `name`      | `string`              | No       | Respondent name                    |
| `email`     | `string`              | No       | Respondent email                   |

SubmitSurveyResponse [#submitsurveyresponse]

| Field             | Type      | Description                  |
| ----------------- | --------- | ---------------------------- |
| `success`         | `boolean` | Whether submission succeeded |
| `thankYouMessage` | `string`  | Thank-you message to display |

***

Full Survey Example [#full-survey-example]

```javascript
const api = new ResytechApi();

// Token comes from the survey link (e.g., emailed to customer)
const token = 'eyJhbGciOiJIUzI1NiJ9...';

// 1. Load the survey
const surveyResult = await api.survey.getSurvey(token);

if (!surveyResult.success) {
  console.error('Survey not found or expired');
  return;
}

const { survey, bookingContext, branding } = surveyResult;

// 2. Render the survey UI
//    Use branding for colors, bookingContext for personalization
console.log(`${branding.companyName} - ${survey.name}`);
console.log(survey.description);

// 3. Collect responses (from your UI)
const responses = {};
survey.questions.forEach(q => {
  switch (q.type) {
    case 'rating':
      responses[q.id] = 5; // user's star rating
      break;
    case 'text':
      responses[q.id] = 'Had a wonderful time!';
      break;
    case 'select':
      responses[q.id] = q.options[0]?.id; // selected option
      break;
  }
});

// 4. Submit
const submission = await api.survey.submitSurvey({
  token: token,
  name: bookingContext.customerName,
  email: bookingContext.customerEmail,
  responses: responses
});

if (submission.success) {
  // Show the operator's custom thank-you message
  console.log(submission.thankYouMessage || survey.thankYouMessage);
}
```