Skip to main content

Handling Customer Data

Several WIIL APIs work with personal information and transaction records — customer identities, contact details, orders, and bookings. This guide explains how that data is accessed and the practices to follow when building on those APIs.

note

This is developer guidance on using the APIs securely — not legal or compliance advice. Consent, retention, and regulatory requirements are governed by your organization's privacy policy and your agreement with WIIL. See Privacy and Compliance.

Which APIs handle customer data​

Treat any field that identifies or can contact a person — name, email, phone, address — as personal information.

CategoryAPIs
Identity & contactCustomers, Customer Groups, Shipping Addresses, Property Inquiries
CommunicationsCommunications, Outbound Calls, Outbound Emails, Outbound SMS
TransactionsProduct Orders, Menu Orders, Service Appointments, Reservations

Access model​

All of these APIs are reached with your API key in the X-Wiil-Api-Key request header. Two things follow from that:

  • Full organization access. A valid key can read and write all of your organization's resources, so it is a highly sensitive credential.
  • Scoped to your organization. Requests can only reach your own organization's data — attempting to access another organization's resources returns 403 Forbidden.

See the Authentication guide for key management, rotation, and error handling.

Keep the API key server-side​

Your API key must never reach the browser or a mobile client. Anyone who can read it gains full access to your organization's customer data.

  • Call the customer and transaction APIs from your backend, not directly from client-side code.
  • Store the key in a secret manager or environment variable — never in source control or shipped bundles.
  • Use HTTPS for every request.

The chat widget is the exception that proves the rule: it runs in the browser but authenticates with data-config-id and data-route-service — not your API key (see the Widget Configuration Guide). So you can embed the widget publicly without exposing credentials, while the sensitive APIs stay behind your backend.

A typical flow:

Browser (widget / your UI)
        |
        v
Your backend  ——  X-Wiil-Api-Key  ——>  WIIL API (Customers, Orders, …)

Collecting information​

The widget's Contact Form is the main point where the platform gathers visitor details (email or phone) before a conversation. When configuring it:

  • Ask for the minimum. The form accepts an email or a phone number — require only what you actually need.
  • Be clear about the ask. Use data-contact-header-text to explain why you're collecting it, and give fields plain labels and placeholders.
  • Fail gracefully. Set helpful data-contact-email-error / data-contact-phone-error messages.

The same principle applies when creating records through the APIs: only send and store the customer fields your use case requires.

Data minimization​

  • Collect and retain the least information needed to serve the customer.
  • Avoid copying personal data into logs, analytics, or third-party tools.
  • Remove records you no longer need, in line with your retention policy.

Privacy and Compliance​

Consent, retention periods, encryption, data residency, and regulatory obligations (e.g. GDPR, CCPA) are governed by your organization's privacy policy and your agreement with WIIL — they are not configured through these APIs. Consult those documents and your legal or compliance team before collecting or processing customer data.