Skip to main content

​
Overview

The Nautilus API allows authorized external systems to interact with the Nautilus platform programmatically. The canonical API is read-only and tenant-scoped. It exposes your organization’s sites, products, checkout links, purchases, contacts, marketing signups, forms, vouchers, links, automations, surveys, cases, Google reviews, and cancellation records, plus POS data for supported organizations. Its machine-readable contract is available without authentication:
The headless form API accepts answers directly through POST /api/forms/{formId}/submissions, without an iframe or a tenant API key. Copy the endpoint and saved field IDs from your form’s Share > Use your own form panel. Forms that require verification, POS enrollment, or file uploads use the hosted flow.

​
Base URL

​
Authentication

Canonical data reads and the legacy message, email, and analytics endpoints require a Bearer token passed in the Authorization header.
Requests with a missing or invalid token receive a 401 Unauthorized response. The Bearer prefix is required and case-sensitive. The headless form submission endpoint does not use Bearer authentication. It uses the published form ID and, when configured, the form’s password. Do not put a tenant API key in browser form code.

​
Key types

Nautilus issues two kinds of API keys:
  • Tenant-scoped keys — bound to a specific organization. All canonical data endpoints require a tenant-scoped key. Sends are attributed to that tenant and use the tenant’s own sender identity (email from your slug-derived address on @mail.nautilus.co, SMS from your configured tenant phone number).
  • Platform keys — legacy Nautilus-issued keys that send as the Nautilus brand (SMS from the Nautilus shortcode, email from contact@mail.nautilus.co). Platform keys work only for the message and email send endpoints.
Most integrations use tenant-scoped keys. Contact Nautilus to provision one for your organization.

​
Tenant isolation for authenticated reads

The organization bound to your API key is the only tenant scope. Requests cannot supply or override an organization ID. Collection queries are always scoped to your organization, and detail endpoints return 404 for both missing and cross-tenant IDs so resource existence is never disclosed. Responses are built from narrow public serializers. They do not expose API credentials, provider configuration, access tokens, webhook secrets, raw provider payloads, or internal workflow data. Form, signup, and survey answer payloads also have sensitive internal keys removed recursively.

​
Canonical resources

All canonical endpoints use GET and share the collection envelope and cursor pagination. The four /api/v1/pos/* resources use the organization bound to your API key to select its POS data source. They support Sonny’s Shared, shared ODBC, and SiteWatch organizations. You do not supply a provider name or organization ID. Unsupported organizations receive 404.

​
POS data conventions

  • Shared ODBC and SiteWatch customer phone filters match valid national and international forms using your organization’s phone country. active=false excludes customers whose activity status is unknown.
  • Timestamps preserve the recorded UTC values. Monetary fields ending in Cents contain integer cents; unavailable fields are null or empty arrays.
  • Shared ODBC and SiteWatch transaction queries require completedAfter when you supply customerId. A missing lower date bound returns 400.
  • Shared ODBC and SiteWatch membership details include the latest 24 billing events and latest 24 status events, newest first. These arrays are recent history, not a complete ledger.
  • For shared ODBC and SiteWatch, missing sale totals fail the request instead of becoming zero revenue. Unavailable gross line amounts are null; recorded net amounts remain available.

​
Migrate existing POS integrations

The previous /api/v1/pos/sonnys/* routes remain available for existing Sonny’s Shared integrations and return deprecation and successor-link headers. Use /api/v1/pos/* for new integrations. When migrating, restart pagination: cursors from the previous routes cannot be reused on the new routes. Google reviews (/api/v1/reviews) are Business Profile reviews mapped to your sites. reviewId is the stable Nautilus identifier and googleReviewId is Google’s. The collection also includes reviews for sites of organizations whose super organization is your tenant, so organizationId is set per review. Deleted reviews and thin Places-API preview placeholders are never returned. Raw provider payloads, AI reply drafts, and dispute analyses are not exposed. Cancellation records include normalized signup discounts (signupDiscounts, hadSignupDiscount) and first-year billing coverage (firstYearPayments, firstYearPaymentCoverage) built from normalized billing events.

​
Headless form submissions

Use POST /api/forms/{formId}/submissions to submit a form rendered on your own website. It accepts flat JSON, URL-encoded form data, and text-only multipart requests. Include the required empty _gotcha bot-trap field and use the saved field IDs as answer keys. The public form ID permits submission only. Reading forms and saved submissions through /api/v1/forms still requires a tenant-scoped key. Forms that require email verification, POS enrollment, or uploads use the hosted flow. Start with Build a headless form, then consult the submission reference for the request and response contract.

​
Legacy endpoints

The following endpoints predate the canonical API. They remain available and unchanged, and are marked deprecated in the OpenAPI document: Analytics endpoints require tenant-scoped keys because they return organization-scoped data.

​
Legacy date parameters

Legacy analytics date filters are interpreted in UTC. For members, retention offers, cancellations, and cancellation survey, date-only lower bounds such as 2026-01-01 start at 2026-01-01T00:00:00.000Z. Date-only upper bounds include the full day and end at 23:59:59.999Z. Cohort start and end values are truncated to their month. Explicit timestamps are used as exact inclusive instants for the other analytics endpoints. Invalid date values are ignored unless an endpoint documents stricter validation. Canonical endpoints are stricter: timestamp filters such as createdAfter must include an explicit UTC offset, for example 2026-07-01T00:00:00Z.