Learn · RxPhoto

Guides & concepts — RxPhoto

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

Request basics

• Protocol: REST over HTTPS.
• Base URL: https://api.rxphoto.com.
• Paths: most endpoints sit under /api/v3/ and end in a trailing slash (e.g. /api/v3/patient/); check each operation in the reference for its exact path.
• Format: primarily JSON request and response bodies — send Content-Type: application/json on POST, PUT, and PATCH. Some operations return files such as application/pdf.
• Verbs: GET reads, POST creates, PUT/PATCH update, DELETE removes. RxPhoto prefers PATCH for updates — send only the fields you want to change rather than the whole object.
• Auth: a single Authorization: Token YOUR_TOKEN header on every request — the token is prefixed with Token and there is no gateway apikey parameter. See Authentication — RxPhoto.
• Field naming: JSON properties are snake_case (e.g. first_name, birth_date, last_visit). This differs from PNE/VISH (PascalCase) and PNP (camelCase).

Pagination

List endpoints are paginated, but the parameters vary by resource — always check the operation's parameter table in the reference. Two styles are in use:

Either way, each list response is an object with a total count, absolute next/previous page URLs (or null at the ends), and the rows in results:

{
  "count": 1287,
  "next": "https://api.rxphoto.com/api/v3/patient/?page=2",
  "previous": null,
  "results": [ { "id": 12345, "first_name": "Jane", ... }, ... ]
}

The simplest way to walk a collection is to follow next until it is null:

def iter_patients(session, base, page_size=50, **filters):
    url = f"{base}/patient/"
    params = {"page_size": page_size, **filters}
    while url:
        res = session.get(url, params=params)
        res.raise_for_status()
        body = res.json()
        yield from body["results"]
        url = body["next"]   # absolute URL to the next page, or None
        params = None        # next already encodes the query string

async function* iterPatients(base, headers, pageSize = 50, filters = {}) {
  const qs = new URLSearchParams({ page_size: pageSize, ...filters });
  let url = `${base}/patient/?${qs}`;
  while (url) {
    const res = await fetch(url, { headers });
    const body = await res.json();
    yield* body.results;
    url = body.next;   // absolute URL to the next page, or null
  }
}

Filtering & search

List endpoints expose rich, field-level filters using a field__lookup convention, plus a general search and an ordering parameter. Available filters vary by resource — the reference lists each endpoint's query parameters.

Shaping the response: fields, omit & expand

Beyond filtering and search, most RxPhoto endpoints accept three parameters that control the shape of each result object. They keep payloads small and save you follow-up requests:

Resource IDs

RxPhoto returns plain integer IDs for all resources — patients, images, bundles, forms, and so on. They appear directly in path parameters and response bodies:

// A patient response — IDs are integers:
{ "id": 12345, "first_name": "Jane", "last_name": "Smith", ... }

// Use the integer directly in the next call (note the trailing slash):
GET /api/v3/patient/12345/

• Store them as integers in your system — no need to treat them as opaque strings.
• They're stable for a given record and safe to use as foreign keys.

Dates & times

• Date and date-time fields are ISO 8601 strings. Filter parameters that accept dates (e.g. birth_date, last_visit) accept YYYY-MM-DD or a full datetime string, and support the __gte/__lte/__gt/__lt range lookups.
• There are also convenience lookups for date parts, such as birth_date__month__gte and last_visit__year__lte.
• Nullable date fields may be null when unset — guard for that in your client. Pass UTC for consistent results across environments.

Errors & status codes

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