Skip to content

Guidelines

Introduction

Align generic APIs offer an integration solution for labs' software allowing the labs to consume iTero scans and services directly to the 3rd party software.

This document describes some of the best practices that are recommended to be used. These are recommendations only and should be used at the partner's discretion.

Please check https://guides.itero.com/ for manuals and training material about iTero.

Terminology

  • This document is using the terms scan, order, and case interchangeably.
  • Lab is an account.

myitero.com

To go through a smooth development process, it is beneficial to be familiar with Align portal myitero.com.

Myitero portal serves both clinic users and lab users. The view is adjusted based on the logged-in user' role.

The portal that is widely used by iTero customers, serves as a reference to the developer of the connection.

Clinical user Clinical user

Lab user Lab user

While developing the software, it is helpful to track the scans in the portal. In case you ask yourself 'where did the scan go' or "why is the scan not listed", checking it on the portal may give you a clue of the scan's status.

Align Accounts and Users

In order to be able to use Align APIs a user should be:

  1. Registered with Align system
  2. Associated with an account (in particular a clinic or a lab)
  3. Has a login option and credentials
  4. Can log in to myitero.com

In case you are missing credentials or need to define a user

Please contact the Professional Services person that is responsible for the integration, or send an email to iTeroAPISupport@aligntech.com

Note

Note that scanners that are part of the integration must be Element 1 or later (legacy scanner are not supported).

Development environment

Development is done through test accounts that allow the partner to use both the API and MyiTero.com for a full ecosystem experience. A VPN is not needed to access development tools.

A connectivity team member takes charge of: - Creating test accounts and users - Configuring an iTero Scanner for development if using a real scanner (Not needed in most cases, since an API-based scanning tool is available) - Providing Client ID and Secret for API access

APIs Base URLs

Align APIs use two base URLs:

  • oauth_base - for authentication calls
  • baseUrl - For initial call to Discovery endpoint
  • Domain/Path URL's - Returned by Discovery, these URL's will be used for general calls to the API

Make sure to have these two paths configurable in your system, so in case of a change, no deployment is required.

This is important since Align is constantly improving its generic API offering. This may result in a change of the URLs. We don't expect frequent changes, however this option should be kept open.

CORS Limitation

If integration solution requires CORS access we recommend to leverage reverse proxy to achieve it.

Flows of API calls

The provided set of API calls holds the logic that enables a full workflow of a lab.

A typical Lab Connector implementation will follow this order of steps:

  1. Authentication
  2. Call to Discovery
  3. Pair to the desired lab
  4. Get orders for lab or handle scan notifications to identify new scans that are ready to view and download
  5. Get order by RX ID – can be useful for some implementations
  6. Download case

Cover all flows

The typical flow would be: a scan is sent from the clinic directly to the lab (direct to lab). The lab can choose to send the case to modeling or to order a physical model. Each step of the process will change the scan files, and the status of the scan. But the scan's order ID does not change. The 3rd party software should consider all scenarios. It may want to store case numbers of scans that are sent to modeling, so it knows how to treat them when they are back.

For more information please refer to the 'ITero Case Flow' site.

New scans

Retrieve new scans

Align API provides two ways to fetch new scans:

  1. Get Orders for Lab - Polling this REST API retrieves all cases that are currently ready. Once a case is downloaded its status will change to “Downloaded” and the scan will not appear in the list of scans that is returned by ‘Get Orders for Lab’ anymore. Note that it is always available for downloaded.

  2. Scan notification webhook – In case of registering to get Scan Notifications, a notification will be sent with every scan that is ready for download. A scan notification includes Rx ID and account number and can be used to get the scan information.

It is recommended to incorporate the two methods. Using the webhook allows operating in an 'interrupt' like mechanism that uses the available resources more efficiently. However, to ensure that no scan is missed it is recommended to poll GetOrders occasionally.

What Artifacts can be downloaded?

The following types of assets are available for download:

  1. Scan 3D file (iDE) - The zip file includes the following:
    1. STL/PLY file
    2. Scan metadata XML files. The most updated XML file for restorative cases is v50.
    3. RX - an HTML file
    4. RX - a PDF file
    5. Thumbnails - orthodontics zip file also includes the thumbnails. Restorative cases do not include it, so if thumbnails are required, they should be retrieved by a separate API call.
    6. More files can be included to specific scans. For example assets that are added to the RX.
  2. Thumbnails - Thumbnails is a set of 6 2D pictures taken from the 3D model.
  3. Screen captures - if taken

Timing matters

Poll for scans

Currently, it is recommended to wait 120 seconds or more between successive calls to Get Orders to avoid multiple retrievals of an order.

Get scans' data with webhook

In rare cases, it might happen that a scan notification (webhook) is received, but the scan is not yet ready. This means that trying to get scan metadata or to download scan files will fail with error 404 "File Not Found". To overcome this shortcoming make sure to apply a retry mechanism to be applied in such cases.

Pair and Un-pair

What does pair do – user to account

A user that consumes Align generic API must pair to the account with which he wishes to work with. A user will pair to a lab account.

Pair again will return the same token, if already paired.

What is un-pair

Un-pair will disconnect the pairing between the user and the account.

Note

  1. Un-pair will affect all paired users for that account.
  2. Un-pair will disconnect the account from its callback URL to receive scan notifications

Prepare for the unexpected

In rare cases, the scan might not be converted and thus not ready for download. This will result in a 404 error (file not found) during a download attempt. When a 404 error occurs, iTero will automatically regenerate the files for that scan. Therefore, it is recommended to retry after 8 to 20 seconds, allowing enough time for scan regeneration. 404 errors are common when lab export settings have been changed.

Limitations

  • Integrations are not supporting legacy scanners. Element 1 and up are welcomed.
  • A user must have a "type" such as "Lab person", "Dentist" etc.
  • A user cannot be both a "Lab person" and a "doctor"
  • A lab person cannot be associated with more than one lab.