Programming Guide

This guide introduces some basic concepts and workflows that will be important as you begin using the Orchestrate Server APIs.

FHIR Specification

The Orchestrate Server offers APIs that are fully compliant with FHIR (Fast Healthcare Interoperability Resources).

Server URL

Each Orchestrate Server system is its own installation, with its own unique configuration.

Throughout this guide, [server URL] refers to the overall URL for your Orchestrate Server.

For example: https://yourorchestrateserver.careevolution.com.

Endpoints

Each Orchestrate Server can be configured with one or more FHIR endpoints. Different endpoints may have different permissions, resources, and operations available.

Throughout this guide, [base endpoint] refers to the URL for a specific FHIR endpoint.

For example, Orchestrate Servers commonly have one FHIR endpoint for regular operations and a separate one for the Provider Directory API. An example configuration might look like:

FHIR Directory

The main home page of every Orchestrate Server is its FHIR Directory, showing what endpoints are available.

For each endpoint, the directory shows what capabilities it has: supported authentication methods, available resources and operations, and more. It is essentially the Capability Statement in human-readable form. The directory also contains links to key guides within the HL7 FHIR Specification for easy reference.

Resources

All FHIR requests are based on resources—modular health data components. For example, a Patient is a resource, as is an Encounter. Resources stand on their own, but may have relationships with each other. An Encounter may relate back to a particular Patient and involve several Observations.

Basic interactions are performed by issuing a HTTP request to the appropriate resource URL. Some sample requests are shown below. See the HL7 FHIR Specification for more details.

Capability Statement

Each endpoint provides a Capability Statement specifying:

• FHIR interface version.
• Authentication endpoints.
• Supported resources, search fields, and operations.

The URL for the capability statement is:

[base endpoint]/metadata

With an accept:application/json header, it returns:

{
    "resourceType": "CapabilityStatement",
    "status": "active",
    "date": "2025-10-08T14:15:20.72644+00:00",
    "publisher": "CareEvolution",
    "software": {
        "name": "Orchestrate Server",
        "version": "1.0.0"
    },
    "fhirVersion": "4.0.1",
    ...
    "rest": [
      "security": { ... }  // Info on authorization endpoints
      "resources": { ... } // Info on available resources
    ]
}

Available Operations

The Capability Statement provides a complete list of available resources, search fields, and available operations. For example, within the Capability Statement, you can see that the Patient resource allows searching by ID and has an export operation, among other things.

{
    "type": "Patient",
    ...
    "searchParam": [
      {
        "name": "_id",
        "definition": "http://hl7.org/fhir/SearchParameter/Resource-id",
        "type": "token",
        "documentation": "Resource id"
      },
      ...
    ],
    "operation": [
      {
        "name": "export",
        "definition": "http://rosetta.careevolution.com/FHIR/OperationDefinition/Patient-export"
      },
      ...
    ]
  },
  ...
}