API Endpoint Reference

Every read endpoint, its query parameters, and the fields each resource returns — accounts, jobs, invoices, appointments, reservations, and more.

Updated 7 hours ago 40 views reference api developer endpoints

API Endpoint Reference

This is the field-level reference for the read side of the API. If you haven't yet, read The Suprata API first for authentication, the base URL, paging, and error codes. Everything here assumes a valid read-scoped key sent as Authorization: Bearer <key>.

Identity & discovery

These need no scope beyond a valid key.

Method & path Returns
GET /v1/me The account this key belongs to (tenant.id, tenant.name, tenant.database), the key's scopes, and the key's label/prefix. Call it first to confirm auth.
GET /v1 A discovery index — every endpoint this key can reach.
GET /v1/openapi.json The full OpenAPI 3.0 spec, for Swagger UI or SDK generators.

How every resource works

Each resource below supports exactly two read endpoints:

  • List — GET /v1/{resource} — returns a cursor-paginated list. Query parameters:
    • limit — page size, 1–200 (default 50).
    • starting_after — an id; returns records after it (this is how you page). Use the previous response's next_cursor.
  • Single — GET /v1/{resource}/{id} — returns one record by its numeric id, or 404.

Records are returned newest first (descending id). The id field is the primary key you use for the single-record lookup and for starting_after.

A note on dates. Some fields are calendar dates (YYYY-MM-DD), some are Unix timestamps (an integer number of seconds — 0 usually means "not set"), and the reservation tables use full datetimes. Each table below flags which is which where it matters.

Customers — GET /v1/accounts

Your customer accounts. (In the app these are "Accounts"; each can have multiple contacts.)

Field Type Notes
id integer Primary key. Use this everywhere (/accounts/{id}, starting_after).
accounttype integer 1 = an individual; anything else = an organization.
organizationname string Company name (organizations).
fname, lname string Person name (individuals).
email, priphone, altphone string Primary contact details.
address1, address2, city, state, zip string Billing address.
balance decimal Current account balance.
accountmanager integer The staff user id who owns the account.
dateadded, lastupdate integer Unix timestamps.

⚠️ Don't confuse id with accountid. id is the primary key you query on. The column literally named accountid is an external reference (e.g. a QuickBooks handle), not the key.

Contacts — GET /v1/contacts

The individual people attached to accounts.

Field Type Notes
id integer Primary key.
fname, lname string Contact name.
coname string Company, if the contact carries one.
email, priphone, altphone string Contact details.
city, state, zip string Location.
dateadded integer Unix timestamp.

Jobs / work orders — GET /v1/jobs

Field Type Notes
id integer Primary key.
jobidentificationnumber string The human-facing job number.
accountid integer The customer (accounts.id).
status integer The job status id.
startdate date Scheduled date (YYYY-MM-DD).
starttime time Scheduled time of day (HH:MM:SS).
summary string Job description.
createdby integer Staff user id.
creationdate, closetime, conversiontime integer Unix timestamps (closetime > 0 means the job is closed).

Invoices & estimates — GET /v1/invoices

A safe projection — the numbers and dates, not internal sync columns.

Field Type Notes
id integer Primary key.
uniqueid string The invoice number printed on the document (what your customer sees).
accountid integer The customer (accounts.id).
jobid integer Linked job, if any.
reservationid integer Linked reservation, if any.
isestimate integer 1 = an estimate, 0 = an invoice.
subtotal, tax, total decimal Money. total is the document total.
amtpaid, amtdue, amtrefunded decimal amtdue is the outstanding balance.
invoicedate, duedate date YYYY-MM-DD.
notes string Free-text notes.
approved, voided, closed integer Unix timestamps that double as flags: 0 = no, > 0 = the time it happened. So voided > 0 means voided; closed > 0 means paid & closed.

Appointments — GET /v1/appointments

Field Type Notes
id integer Primary key.
jobid integer The job this appointment belongs to (reach the customer via the job).
servicelocationid integer Where the work happens.
startdate, enddate date YYYY-MM-DD.
starttime, endtime time HH:MM:SS.
status integer 0 Unscheduled · 1 Scheduled · 2 Confirmed · 3 Completed · 4 Cancelled · 5 On Hold · 6 Working · 7 Dispatched.
notes string
author integer Creating staff user id.
confirmtime, dispatchtime integer Unix timestamps (flags: > 0 = confirmed / dispatched).

Reservations — GET /v1/reservations

Marina/asset bookings. These tables use full datetimes (YYYY-MM-DD HH:MM:SS), not Unix integers.

Field Type Notes
id integer Primary key.
reservation_number integer The human-facing reservation number.
customer_id integer The customer (accounts.id).
reservation_type_id integer The reservation type.
status string One of draft, reserved, checked_in, active, ready_for_checkout, completed, canceled, no_show.
start_ts, end_ts datetime Booking window.
checkin_ts, checkout_ts datetime Null until they happen.
master_invoice_id integer The reservation's invoice (populated at settlement/checkout).
notes, title string
created_at, updated_at datetime

Service agreements — GET /v1/contracts

Field Type Notes
id integer Primary key.
contractname, nickname string Agreement name.
accountid integer The customer.
contractstatus integer 1 = open, 0 = closed.
contractdate date
autoclosedatetime date Scheduled auto-close date.
issubscription integer 1 = a recurring subscription.

Passes & permits — GET /v1/permits

Field Type Notes
id integer Primary key.
account_id integer The customer the permit belongs to.
status string The permit's current state.
end_date date Expiration date.

Price list items — GET /v1/pricelist

Field Type Notes
id integer Primary key.
producttitle string Item name.
shortdesc string Description.
sku string The item's SKU.
mfgsku, vendorsku string Manufacturer / vendor SKUs.
category string Item category.
baseprice, msrp decimal Pricing.
active integer 1 = sellable.

Payments — GET /v1/payments

A deliberately narrow projection — card and token columns are never exposed.

Field Type Notes
id integer Primary key.
invoiceid integer The invoice paid.
accountid integer The customer.
amount decimal Payment amount.
paydate date/timestamp When it was recorded.
paytype string Method (cash, card, ACH, …).
paystatus string Settlement status.

Common stumbling blocks

  • Resolving names. The API returns ids (accountid, jobid), not names — fetch the related record (e.g. GET /v1/accounts/{accountid}) to get the display name. Cache them; a customer's name rarely changes.
  • Timestamp 0 is not "epoch 1970". On the flag-style fields (voided, closed, approved, confirmtime), 0 means "hasn't happened". Test > 0, don't format 0 as a date.
  • Estimates and invoices share this endpoint. Filter on isestimate client-side (1 = estimate). There's no separate /estimates route.