FHIR RESTful API

Payerbox exposes the full base FHIR R4 RESTful API at /fhir — every interaction defined in the FHIR HTTP spec is available without per-resource configuration. This page is a summary of the surface; for full semantic detail, modifier reference, and edge-case behavior, see the Aidbox docs on REST API CRUD and FHIR Search.

The /fhir base uses FHIR-format resources. Aidbox also exposes a non-FHIR / base which uses Aidbox's native resource format — use /fhir for any FHIR-conformant integration.

Endpoints

Auth

SMART Backend Services and Client Credentials. The caller's OAuth client must be allowed (via Aidbox access policies) to perform the interaction on the target resource type. Any interaction may return 403 Forbidden if the client is not authorized. See Authentication.

Create

Endpoint

POST /fhir/<type>

Response codes

Example

POST /fhir/Patient
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "name": [{"given": ["Bob"], "family": "Smith"}],
  "gender": "male",
  "birthDate": "1970-05-15"
}

HTTP/1.1 201 Created
Location: /fhir/Patient/<id>/_history/1
ETag: W/"1"
Last-Modified: 2026-05-15T13:40:00Z

{
  "resourceType": "Patient",
  "id": "<id>",
  "name": [{"given": ["Bob"], "family": "Smith"}],
  "gender": "male",
  "birthDate": "1970-05-15",
  "meta": {"versionId": "1", "lastUpdated": "2026-05-15T13:40:00Z"}
}

Conditional create

POST /fhir/<type>?<search-params>

Or pass the search criteria in the If-None-Exist header. Outcome depends on the number of matches:

• No matches — server performs a normal create (201).
• One match — server returns the existing resource (200), no new resource is created.
• Multiple matches — 412 Precondition Failed; the criteria were not selective enough.

The same ifNoneExist field is supported inside Bundle.entry.request for transaction bundles (case-sensitive — must be spelled exactly ifNoneExist).

Read

Endpoint

GET /fhir/<type>/<id>

Response codes

Example

GET /fhir/Patient/<id>

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "<id>",
  "name": [{"given": ["Bob"], "family": "Smith"}],
  "gender": "male",
  "birthDate": "1970-05-15",
  "meta": {"versionId": "1", "lastUpdated": "2026-05-15T13:40:00Z"}
}

vread

GET /fhir/<type>/<id>/_history/<vid>

Returns a specific version of the resource. <vid> is the meta.versionId value (typically a monotonically-increasing integer).

Update

Endpoint

PUT /fhir/<type>/<id>

Replaces the resource. If no resource exists at <id>, one is created (upsert semantics). The id cannot be changed once the resource exists.

Response codes

Example

PUT /fhir/Patient/<id>
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "<id>",
  "name": [{"given": ["Bob"], "family": "Smith"}],
  "gender": "male",
  "birthDate": "1970-05-15"
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "<id>",
  "meta": {"versionId": "2", "lastUpdated": "2026-05-15T13:41:00Z"},
  "name": [{"given": ["Bob"], "family": "Smith"}],
  "gender": "male",
  "birthDate": "1970-05-15"
}

Conditional update

PUT /fhir/<type>?<search-params>

Outcome depends on the number of matches:

• No matches — server performs a create.
• One match — server performs the update against the matching resource (the id in the request body is ignored).
• Multiple matches — 412 Precondition Failed.

Versioned update (optimistic concurrency)

Send If-Match: <versionId> to require that the current meta.versionId matches. On mismatch the server returns 412 Precondition Failed with an OperationOutcome (code: conflict).

Send If-Match: * to update-only (refuse to create if the resource does not exist) — returns 412 instead of creating.

Patch

Endpoint

PATCH /fhir/<type>/<id>

Three patch dialects are supported — pick by Content-Type (or by the _method query parameter):

If the dialect is not specified, Aidbox infers it: Parameters resourceType → FHIRPath Patch; array body → JSON Patch; otherwise → Merge Patch.

A successful patch fires the same update event as PUT. No-op patches (replacing a field with its current value) return 200 OK but do not fire an event.

Example

PATCH /fhir/Patient/<id>
Content-Type: application/merge-patch+json

{"active": false, "telecom": null}

PATCH /fhir/Patient/<id>
Content-Type: application/json-patch+json

[
  {"op": "replace", "path": "/active", "value": false},
  {"op": "remove",  "path": "/telecom"}
]

PATCH /fhir/Patient/<id>
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "operation",
    "part": [
      {"name": "type",  "valueCode":   "replace"},
      {"name": "path",  "valueString": "Patient.active"},
      {"name": "value", "valueBoolean": false}
    ]
  }]
}

Delete

Endpoint

DELETE /fhir/<type>/<id>

Response codes

A subsequent GET /fhir/<type>/<id> returns 410 Gone.

Example

DELETE /fhir/Patient/<id>

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "<id>",
  "meta": {"versionId": "3", "lastUpdated": "2026-05-15T13:42:00Z"},
  ...
}

Conditional delete

DELETE /fhir/<type>?<search-params>

• No matches — 204 No Content.
• One match — server performs a normal delete.
• Multiple matches — 412 Precondition Failed by default. To delete all matches, send x-conditional-delete: remove-all.

Search

Endpoint

GET /fhir/<type>?<param1>=<value1>&<param2>=<value2>&...

Returns a Bundle of type: searchset with the matched resources in entry[].resource, a total count, and link[] entries for pagination (first / prev / self / next / last).

Search parameter types

Each search parameter has a type, declared on the SearchParameter resource, that drives matching semantics:

Modifiers

Append a modifier with a colon to refine the match (<param>:<modifier>=<value>):

Common parameters

_include and _revinclude

_include=<source-type>:<search-param>[:<target-type>]
_revinclude=<source-type>:<search-param>[:<target-type>]

Append :iterate to follow the reference chain recursively.

GET /fhir/Patient?_include=Patient:organization
GET /fhir/Organization?_revinclude=Patient:organization
GET /fhir/Observation?_include=Observation:patient&_include:iterate=Patient:link

Chaining

Filter by a property of a referenced resource:

GET /fhir/Patient?general-practitioner:Practitioner.name=Oz
GET /fhir/Practitioner?_has:Patient:general-practitioner:gender=male

• Forward chain — <reference-param>:<target-type>.<terminal>
• Reverse chain (_has) — _has:<source-type>:<reference-param>:<terminal>

Chains of any length are supported; mix forward and reverse with . and : joins.

Example

GET /fhir/Patient?name=Smith&gender=male&_count=2&_include=Patient:general-practitioner

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "<id>",
        "name": [{"family": "Smith", "given": ["John"]}],
        "gender": "male"
      },
      "search": {"mode": "match"}
    }
  ],
  "link": [
    {"relation": "self", "url": "/fhir/Patient?name=Smith&gender=male&_count=2&_page=1"}
  ]
}

Transaction and batch

POST /fhir/

Submit a Bundle of type: transaction (all-or-nothing) or type: batch (per-entry, independent failures). Each entry.request carries an HTTP method and URL — the server applies the entries and returns a Bundle of type: transaction-response / batch-response with the per-entry outcomes and resolved references.

Validate

Dry-run validation against the FHIR core schema and any profile the resource claims via meta.profile. Always returns 200 OK; the outcome is in OperationOutcome.id — allok or validationfail.

POST /fhir/<resourceType>/$validate
POST /fhir/<resourceType>/<id>/$validate

The same validator runs on every Create / Update / Patch — when the resource carries a meta.profile from one of the loaded Implementation Guides, a failed write returns 422. See $validate in the Aidbox docs for modes, profile parameter, and async validation.

Errors

All 4xx and 5xx responses carry an OperationOutcome body describing the failure.

For full semantic detail — additional modifiers, advanced _filter operators, custom SearchParameter registration, AidboxQuery / Search resource / dot-expressions as alternatives to FHIR Search — see the Aidbox REST API docs. For Payerbox-specific operations layered on top of this base API, see the Operations index.