Sequoia Project Healthcare Directory Implementation Guide
1.0.8 - Release 1 United States of America flag


Official URL: Version: 1.0.8
Active as of 2024-05-20 Computable Name: SequoiaProjectHealthcareDirectoryImplementationGuide

The Sequoia Project Healthcare Directory implementation guide (IG) is an abstract IG designed to accommodate the underlying needs of Sequoia Project initiatives. This implementation guide is not intended to be implemented directly.

This IG is based on US Core, and uses uses the same conformance guidance as that IG, including the definition of must-support.

Conventions Used

XML examples in this documentation use the following formatting convention:

Text to be entered at a terminal uses the following formatting convention:

curl -X GET “”

Source code in this documentation use the following formatting convention:

if (x) puts “here” else puts “in else” end

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and”OPTIONAL” in this document are to be interpreted as described in IETF RFC 2119 which currently can be found at the URL:

Conformance statements use the following formatting convention:

CONF: Testable assertion text.


This document is intended to cover information necessary to successfully understand the approach and connect to the Sequoia Project Healthcare Directory environments. The Sequoia Project will endeavor to maintain the directory with a high degree of stability with respect to the structure of the entries and the processing model until FHIR matures. FHIR has many additional capabilities that have not been implemented this time due to lack of apparent needy by Sequoia Project initiatives. Some unimplemented features include additional query parameter support, historical version retrieval, non-directory resources, and more. The Sequoia Project welcomes feedback on additional capabilities that may help participants use the directory more effectively. Any subsequent changes to the directory will be implemented in a backward compatible manner, if possible.


This document is copyright 2017-2021 by The Sequoia Project. All rights reserved world wide.

The Sequoia Project is a registered trademark of The Sequoia Project.

HL7 is a registered trademark of Health Level Seven.

FHIR is the registered trademark of HL7 and is used with the permission of HL7.


This document is intended for software engineers, architects, configuration managers, and project managers involved with the creation, deployment, and run-time operational support of client software using The Sequoia Project Healthcare Directory. It is assumed that the reader has at least minimal exposure to the HL7 FHIR Standard for Trial Use version 3, and to directory concepts in general. Deployment teams are expected to be proficient in the curation of directory data, and have access to expertise, within their organizations, in secure deployment architectures (X.509, TLS, security best practices, etc.).

Anticipated Roadmap

The version 1.0 Healthcare Directory is anticipated to remain stable from its initial deployment until the current FHIR trial standard becomes stable and fully balloted by the HL7 community. At that point, we plan to update the Sequoia Project Healthcare Directory to version 2.0 to reflect the balloted version of the FHIR standard.

Operationally, we anticipate providing sufficient overlap between version 1.0 and 2.0 of the Sequoia Healthcare Directory to allow for a graceful migration by all those using the directory in production. Specifically Sequoia plans to operate the 1.0 provider directory for approximately 1 year after version 2.0 is put into production use. During that 1 year period of time, all users of the directory are expected to complete their migration to version 2.0. After 1 year of dual operation, the 1.0 directory will be decommissioned.

Please see the change log in this documentation for more information.


As previously mentioned, access to each directory environment requires the presentation of a valid API Key. The API key is a value that is unique to each client and for each environment. The key serves to perform several functions:

  1. It allows the Sequoia Project Healthcare Directory server to immediately, and efficiently, discard invalid queries, such as those from an unauthorized client software package.
  2. It allows for audit logging of requests.
  3. It allows the server to provide more detailed diagnostics to client applications.
  4. It allows The Sequoia Project to identify the organization associated with errant queries, excessive utilization, or other issues.

To obtain an API key please send an email to Once your email has been received by the technical support system, you will automatically be assigned a ticket ID (called a conversation ID), and an automatic response will be sent to your organization to acknowledge receipt of your email. If you do not receive an automatic response, then the support system likely did not receive your support request.

One key will be needed for each environment. A key intended for VAL cannot successful be used in PROD, for example.

To present the key upon an API call to the Sequoia directory, the following syntax must be used:

GET http:///Organization/?apikey=1234


GET https:///Organization/?apikey=1234

Where the value <base-url> is replaced by the value provided to you when directory access is granted, and the value 1234 is replaced by your API key value.

Design Concepts

The Sequoia Project Healthcare Directory is an implementation of the Argonaut FHIR Provider Directory work ( and the current HL7 FHIR Standard for Trial Use v3 (STU3) version 1.8.0 which, as of the time of this writing, has incorporated the Argonaut work (with some changes). The Sequoia Projects overall approach is to leverage the base Argonaut and HL7 FHIR work, with respect to provider directory use cases and resources, with only minimal added constraints and extensions.

Theory of Operations

The directory supports an operational model by which the client software retrieves the contents of the directory quickly and efficiently using one of several recommended practices and then obtains incremental updates on a periodic basis.

Clients may include an optional query parameter indicating their preferred data format for the response (JSON vs XML), and additional parameters such as search criteria. Additional directory capabilities may be added in the future if needed by organizations using the directory, such as to support additional query parameters. A successful call results in a document returned containing a FHIR Resource or a FHIR Bundle, which contains Entries for each Organization resource with scope of the query results. A single Resource (not a Bundle) is returned for REST calls retrieving a specific resource such as Organization\1. A FHIR Bundle is returned for RESTful calls performing searches, such as?id=1. Returned Organization resources will contain general information about the entity being described, such as its general office address(es), telephone numbers, etc. The returned Organization resource will include any associated EndPoint resources as Contained resources. The EndPoint resources specify the technical web services end points for an entity listed in the directory. The Organization and EndPoint resource structures have been extended by Sequoia to meet the needs of its communities, including more detailed information than is present in the base FHIR EndPoint resource type. The extension semantics and syntactic structure are discussed in detail elsewhere in this document.

For efficiency, the client software may use HTTP cache control mechanisms to specify a retrieval of the entries, i.e. Organization resources and their children, that have been modified since a specific date/time. HTTP etags are also implemented by The Sequoia Project Provider Directory allowing for simple change detection logic. The returned document also contains embedded date/time stamps indicating the most recent update to that element.

Once the client software receives the HTTP response from the Sequoia directory, it is expected to robustly process success or failure conditions. Sample responses are presented in the Examples Section.