Learn

Guides & concepts

The conventions that hold across every resource. Learn these once and the whole API becomes predictable.

Request basics

• Protocol: REST over HTTPS; resources under /api/v1.
• Format: JSON request and response bodies. Send Content-Type: application/json on POST and PUT.
• Verbs: GET reads, POST creates, PUT updates, DELETE removes.
• Auth: a gateway apikey (query string) plus HTTP Basic credentials on every request — see Authentication.
• Field naming: JSON properties are PascalCase (e.g. FirstName, CompanyId).

Pagination

List endpoints (those returning collections) page their results using two query parameters:

Walk a collection by incrementing Page until a page returns fewer rows than you asked for (or none):

def iter_customers(session, base, rows=50, **filters):
    page = 1
    while True:
        res = session.get(f"{base}/customers",
                          params={"Page": page, "Rows": rows, **filters})
        res.raise_for_status()
        batch = res.json()
        if not batch:
            return
        yield from batch
        if len(batch) < rows:   # last page
            return
        page += 1

async function* iterCustomers(base, headers, rows = 50, filters = {}) {
  let page = 1;
  for (;;) {
    const qs = new URLSearchParams({ Page: page, Rows: rows, ...filters });
    const batch = await (await fetch(`${base}/customers?${qs}`, { headers })).json();
    if (!batch.length) return;
    yield* batch;
    if (batch.length < rows) return; // last page
    page++;
  }
}

You don't have to page blindly: most list responses include a set of Data* headers describing where you are in the result set. Read them to size your loop or build a pager.

Filtering & search

Many list endpoints accept filter parameters in the query string. They vary by resource, but common ones include:

Resource IDs

IDs returned by the API (such as CustomerId, CompanyId, LeadSourceId) are opaque, encrypted, URL-safe strings — not raw database integers.

• Treat them as opaque tokens. Don't parse, increment, or construct them. Pass them back exactly as received.
• They're stable for a given record, so you can store them as foreign keys in your own system.
• Related IDs nest naturally: a customer's CompanyId can be used directly anywhere a company ID is expected.

// A customer ID looks like an opaque string, not a number:
{ "CustomerId": "9d4Kx2...", "CompanyId": "Aa01...", "FirstName": "Ada" }
// Use it directly in the next call (these customer sub-resources use POST):
POST /api/v1/customers/9d4Kx2.../Appointments

Dates & times

• Date and date-time fields are returned as strings. Many filters accept a plain YYYY-MM-DD date.
• Nullable dates (e.g. Birthday, LastVisit) may be null when unset — guard for that in your client.
• When sending a date range, pass both StartDate and EndDate unless the endpoint says one is optional.

Companies & locations

A PatientNow Essentials account can span multiple companies/locations. Most resources accept a CompanyId filter so you can scope reads and writes to a specific location. Fetch the list of companies from GET /api/v1/companies and pass the relevant CompanyId through to other calls.

Memberships vs. membership programs PNE

These are two different resources, and mixing them up is a common source of "the name comes back blank" confusion:

Errors & status codes

The API uses standard HTTP status codes. The status line is the primary signal; a JSON body may accompany errors with more detail.

Rate limits

Requests are throttled at the gateway. Your gateway apikey identifies your integration's app, and each app is tied to a plan that sets how many requests you may make per window. Exceed it and the gateway returns 429 Too Many Requests until the window resets — your credentials are still valid; you're simply over quota.

The standard plan allows 1,000 requests per day. If your integration needs more, higher-volume plans are available — contact your PatientNow representative to have your app moved to a larger quota.

Webhooks (events) PNE

Rather than polling for changes, you can register webhooks under api/v1/events/webhooks to be notified when data changes. Manage your registered webhooks through that resource.