The Practice -> Cloud API is the unified API for integrating a Practice Management System with services provided by the Slipstream ecosystem. If you need to invoke an action or query data that is held in a slipstream service, this is the API to use.

This API has 2 distinct kinds of authentication:

• Onboarding:
  Using this API requires a username and password which will be issued to you by the Bifrost team
• Everything else:
  Use the API keys issued by the onboarding APIs to perform actions in the context of a practice site or organisation.

Slipstream is designed to work with multiple PMS systems and so has a fairly flexible design for practice grouping and billing.

Practice Hierarchy

• Practice Site
  A physical brick and mortar practice, where dentistry actually happens. This is sometimes referred to simply as a site for brevity.
  Every practice site will have an owning and a billing organisation (usually the same one).
• Organisation
  A grouping of practice sites under an entity.
  • Owning Organisation
    An organisation that owns one or more practice sites. For multi-site / corporate customers, this represents the entity or brand which owns the physical practices.
    Every practice site must have exactly one owning organisation, even if it only owns itself.
    The practice site onboarding API will automatically create organisations for single site practices if you do not explicitly link them to an existing organisation.
  • Billing Organisation
    The organisation that will be billed for the services used by the practice sites. This may be different from the organisation that owns the practice site, but if it is not specified then the owning organisation is also the billing organisation.

---

Identifiers

• Site Slug
  A short URL-safe identifier assigned by Slipstream to a practice site that is guaranteed not to change.
  Example: fGTfxr
• Organisation Slug
  A short URL-safe identifier for an organisation that is guaranteed not to change.
  Example: GflkMNL
• PMS Specific Identifier
  What you call the entity in the source PMS system (e.g. Dentally) the value should be unique within the PMS system. Examples:
  • Site Identifier:
    • Dentally: aba64a36-2176-4c02-a5cd-6f5f5908e055 (GUID)
    • Exact: UK1234 (string)
  • Organisation Identifier:
    • Dentally: b529cd1e-7389-4630-8771-885816eee796 (GUID)
    • Exact: <None> (Exact does not natively have the concept of organisations - will need to generate one)

Examples

All of the APIs offered here support application/json as the primary request and response format.

---

For specific data types we use the following standards

Type	Standard	Example
Timestamps	ISO 8601	2023-09-27T22:45:12.2473254+13:00
Countries	ISO 3166 alpha-3	NZL
Geolocation	ISO 6709 (latitude + longitude)	+38-097/
Currency	ISO 4217	NZD
Phone	E.164	+64271234567

---

For errors we use ProblemDetails

---

Events are all delivered via webhook and will be delivered to the URL you specify when subscribing in CloudEvent format, serialized as Json.

We recommend that you use one of the open source SDKs for handling the received events:

Ruby | C# | Python | JS | Java

In addition to the standard spec we use these extension attributes:

Attribute	Type	Description	Reference
siteslug	String	The slug of the practice site the event pertains to.
expirytime	Timestamp	The deadline for the event to be delivered. Discarded if not delivered by this time.	CloudEvents Spec
intendeddeliverytime	Timestamp	The time the event is intended to be delivered at. Not delivered before this time.
traceparent	String	The correlation ID for correlating events.	CloudEvents Spec
priority	Integer	Priority of the event for time-sensitive processing.	Normal (0), High (1), Realtime (2)
organisationslug	String	The slug representing the organisation the event pertains to.
billingorganisationslug	String	The slug for the organisation to be billed for the event. Defaults to organisationslug if not specified.
product	String	Identifier of the product that owns the event (e.g. dentally, exact).
dataref	UriReference	A URI using the valet-key pattern to retrieve full data. Use when the payload is large	CloudEvents Spec

Example Event

{
  "specversion": "1.0",
  "datacontenttype": "application/cloudevents+json",
  "source": "https://hsone.app/schema/hso-slipstream-urlshortener",
  "type": "Slipstream.UrlShortener.UrlCreated",
  "slipstreamorganisationidentifier": "GflkMNL",
  "traceid": "00-b7232b4bc06a79d5c89e2c06d1b30f83-964b5c3492e23588-00",
  "traceparent": "00-b7232b4bc06a79d5c89e2c06d1b30f83-964b5c3492e23588-00",
  "partitionkey": "hsone.app-Slipstream.UrlShortener.UrlCreated",
  "priority": 1,
  "slipstreampracticeidentifier": "lwkpcgsx",
  "time": "2023-10-17T14:33:42.0188871+13:00",
  "id": "a37b2e58-3cc0-4667-a590-79d14e7c98ac",
  "data": "{\"EventId\":\"a37b2e58-3cc0-4667-a590-79d14e7c98ac\",\"EventType\":\"Slipstream.UrlShortener.UrlCreated\",\"LongUrl\":\"https://google.com/search\",\"SiteSlug\":\"string\",\"ShortUrl\":\"https://localhost:7001/hwpcVTx\",\"Timestamp\":\"2023-10-17T14:33:42.0188871+13:00\",\"UrlId\":\"hwpcVTx\"}"
}

Capabilities are a set of tags that a practice site sends to the practice registry to indicate what slipstream functionality it can support and is enabled. You should update the capabilities of a practice site whenever the capabilities change, this may be on software update, or when a new feature is enabled.

These can be managed via the practice site endpoints once a practice site has been onboarded

List | Update | Add | Check | Remove