Skip to content

Guidelines

Introduction

Align generic APIs solution for clinics allows establishing a secure connection between the 3rd party software used in the clinic to iTero data and services.

This document describes some of the best practices we recommend using. 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.
  • A clinic 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).

Contact to Account Relationship

The relationship of a doctor to a clinic is N to N:

  • A doctor can be associated with one or more clinics
  • A clinic can have one or more doctors

A doctor that is associated with multiple clinics uses one set of credentials (email/password) for authentication. The user will be able to pair to any of the clinics he is associated with (and is configured for the integration).

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 to enable a full workflow of a clinic.

A typical DPMS implementation will follow this order of steps:

  1. Authentication
  2. Call to Discovery
  3. Pair to the desired clinic
  4. Get Practice Configuration – so the clinic's data that is required for a scan request is available for the software
  5. Scan Request – Push an RX to the scanner
  6. Get orders for practice or handle scan requests to identify new scans that are ready to view and download

Note

This is a common use case. A DPMS application developer can choose not to follow this typical path.

Cover all flows

Restorative cases can be sent to a lab. The lab can choose to send the case to modeling or to order a physical model. The scan files might be changed in each step of the process but the Order ID will not change. The calling application 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.

New scans

Retrieve new scans metadata

Align API provides two ways to fetch new scans:

  1. Get Orders for Practice - Polling this REST call will make sure to list all cases that are in a "Completed" status.
    All ready cases of the clinic will be returned based on the filtering (by date, chart number, etc.)

  2. Scan notification webhook – In case of registering to get Scan Notifications, a notification will be sent with every ready scan. Criteria are the same as for the list of scans that are returned by getting Orders. Once a scan notification is received it includes Rx ID that can be used to get scan information. Note that there is no retry option in case of a missed notification.

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?

There are three types of assets for download:

  1. Thumbnails - Thumbnails is a set of 6 2D pictures taken from the 3D model.

  2. 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 v24. For orthodontics cases it is v50.The package includes also older versions of the files for backwards compatibility purposes.
    3. RX - an HTML file
    4. 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.

  3. Screen Captures - Zip file includes screen captures with and without annotations

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.

Patient Names Consistency

Patients on myitero.com and the scanner are identified by three parameters:

  1. First name
  2. Last name
  3. Chart number

If all three are identical to those of an existing patient, the scan will be associated with this patient. Note that if a scan is completed with a patient name that is not correct or contains a typo, a new patient will be created in Align's system. Merge of patients is currently not available.

Chart number is not mandatory if an RX is generated from myitero.com or the scanner. It is mandatory if the RX is generated by the generic API 'Scan Request'.

The best practice at this point is:

  1. Don't leave chart number empty
  2. Use the DPMS unique identifier in iTero. This means that the patient identification number/string in the DPMS serves as the chart number in iTero.
  3. As a clinic, before starting to use a DPMS system, it is recommended to make sure all patients' names and chart numbers in iTero are correct. A patient's name can be updated on the scanner, in myitero.com or by the API.

Pair and Un-pair

What does pair do – user to account

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

If you pair, and the pair again, the same token will be returned.

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 general, we expect all cases to be completed correctly and be available to work with via the API. However, it is a good practice to make sure your application is prepared to handle problematic cases, so no case is missed.

As noted, a case will be available to download if it has all files ready:

  1. IDE file (zip)
  2. Thumbnails
  3. Ready to view in myitero.com portal

These three files’ links will be returned with the Get Orders request, but it may happen that one of them (iDE in particular) will be missing. In this case, the file will not be available for download and require manual handling:

  • It may be available for download from myitero.com
  • It may be available to download after a brief (40 to 80 seconds interval) wait time to regenerate the IDE file if a doctor changes export settings.
  • If not, it is recommended to contact Align support

Limitations

  • Integrations are not supporting legacy scanners. Element 1 and up are welcomed.
  • A user must have a "type" such as "Dentist".
  • A user cannot be both a "Lab person" and a "doctor"