LMS

The iTero Lab Connector API allows designated labs to automatically retrieve iTero cases as specified by the doctor in the iTero Rx.

Cases are delivered directly to the lab’s software in a predefined open format, ensuring seamless integration. If additional scanning is needed, labs can easily return cases to the doctor for further action.

With secure authentication, iTero credentials only need to be entered once during the initial pairing process, enhancing convenience and security.

Check Authentication and Pairing to learn more about the pairing process.

Definitions, Acronyms, Abbreviations¶

Term	Description
Myitero.com	iTero portal to manage account and cases
Production environment	Live environment
Redirect URL	URL to which the response should be returned
Callback URL	URL to which a notification is sent upon scan completion

Lab Connector API Overview¶

iTero intra-oral scanners capture the scanned data in a native proprietary iTero format, which can be exported to variety of 3D formats and used by 3^rd party systems.

The iTero Lab Connector API enables the retrieval of artifacts into the 3^rd party system.

The API uses the following REST services:

Get Orders – Returns the list of iTero cases that are ready for download.
Get Order by Rx Id – Returns the order details of the passed Rx Id
Callback Request – Notification upon a ready scan
Download Asset - Downloads the zip file containing the exported 3D files or image thumbnails of a specific order.
Return Scan – Returns a specific order back to the doctor for rescan.

Dynamic Domain and Base URL¶

To offer a robust and flexible solution, the domain and path of all endpoints are returned to the caller via an API (Discovery API).

The caller should use these returned values (and avoid hardcoding). Since this is a new feature, the BaseUrl commonly used by many iTero API consumers is still supported. This document outlines both approaches.

For more information about the Discovery API, please refer to the ‘Authentication and Pairing’ page .

All response bodies are in JSON format.

Prerequisites¶

Authentication and pairing must be completed before calling Lab Connector API- resulting with:

access_token
refresh_token

For more information about the pairing process, please refer to the ‘Authentication and Pairing’ page.

Lab Connector Endpoints¶

Get Orders¶

To retrieve the 3^rd party lab’s current orders, use the following GET call:

Title	URL
Discovery API	{{Domain}}/{{Path}}/orders/lab
Legacy	{{baseUrl}}/api/third-party/v2/orders/lab

Listed cases¶

Cases that are listed as a result of Get Orders will arrive in the following statuses:

Case Flow	Status
Received from clinic	Ready for Download
Received from modeling	Lab Review

Access token that is returned in pairing step Use type of ‘Bearer Token’

Query Parameters¶

Key=queryParams.offset, Value=0 Number of orders to skip.
Key=queryParams.pageSize, Value=1024 Number of orders to retrieve. Maximum number is 1024

Orders are returned from oldest to the most recent. In order skip ahead to more recent orders use the offset variable.

Response¶

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
401	Unauthorized error	1. Wrong token 2. Missing token	Double-check that the call is using the correct pairing token
500	Internal Server error	/	A retry mechanism

In case of returned code of 200, the following response will be returned:

{
    "Data": {
        "HasMore": bool,
        "PageSize": number,
        "Offset": number,
        "Results": [
                {
                "ProcedureName": string,
                "ProcedureTypeName": string,
                "Urls": {
                    "MyiTero3DViewerUrl": string,
                    "IDEFileUrl": string,
                    "ThumbnailsUrl": string,
                    "ScreenCaptureUrl": string
                        },
                "OrderId": number,
                "DoctorId": number,
                "CompanyId": number,
                "PatientId": number,
                "OrderCode": string,
                "ScanDate": date,
                "DueDate": date,
                "PatientName": string,
                "PatientChartNumber": string,
                "CompanyName": string,
                "DoctorName": string,
                "DoctorLicenseNumber": string,
                "RxId": Guid,
                "CaseType": string,
                "Status": string,
                "ScanningOperatorId": number,
                "ScanningOperatorName": string,
                "ScanningTime": number,
                "LabId": number,
                "LabName": string,
                "Notes": string,
                "Preps": [],
                "ScannerModelDescription": string,
                "ScannerModelId": int
                 },
                [. . . More scans info]
        "Status": number
            }
}

The following tables list the information that is returned in the Data section of the response:

Field	Sub/Field	Type	Description
HasMore	/	Boolean	True if more orders are available for retrieval, otherwise, false
PageSize	/	Number	Number of orders to retrieve. Maximum number is 1024
Offset	/	Number	Paging is implemented by the parameters Offset and PageSize together. Use 0 to get the first batch of scans. Increase the offset by PageSize to get the next batch until HasMore is false. Most recent scans are listed last.

The Results returned in the Data section of the response are:

Subfield	Type	Description
ProcedureName	String	Name of Procedure
ProcedureTypeName	String	Name of procedure type
MyiTero3DViewerUrl	String	MyiTero.com 3D scan viewer URL
IDEFileUrl	String	URL to retrieve STL/PLY artifact
ThumbnailsUrl	String	URL to retrieve Thumbnails artifacts
ScreenCaptureUrl	String	URL to retrieve scan's screenshots
OrderId	Number	Order Id of the order available for retrieval
DoctorId	Number	Id of the person that performed the scan
CompanyId	Number	Id of the company that performed the scan
PatientId	Number	Deprecated value
OrderCode	String	Order code of the order available for retrieval
ScanDate	Date	Order’s scan date
DueDate	Date	Restorative orders - Expected delivery date of the product from the lab Invisalign orders - Order creation date
PatientName	String	Order’s patient name
PatientChartNumber	String	Order’s patient chart number
CompanyName	String	Name of the company that performed the scan
DoctorName	String	Name of the person that performed the scan
DoctorLicenseNumber	String	License number of the person that performed the scan
RxId	GUID	ID of scan’s Rx
CaseType	String	- Expanded - Full Arch - Quadrant - Reference Model - iRecord
Status	String	Order status: - Ready for Download - Lab Review
ScanningTime	Number	Number of seconds of scan
LabId	Number	ID of the lab that received the scan
LabName	String	Name of the lab that received the scan
Notes	String	Notes of the doctor
Preps	List	Array of preps with their attributes, such as type of unit, tooth number etc.
ScannerModelDescription	String	Scanner model used to create the order
ScannerModelID	Int	Scanner model unique identifier

Status of the call will be 1 for a success call. Otherwise 0

Note

Use the returned links to download assets. This will make sure the call does not break in case of a change in the URLs.

Procedures and Types¶

ID	Procedure Name	Type Name
1	Study Model - iRecord	- Ortho Model/iCast
2	Invisalign / Vivera	- Invisalign Aligners - Invisalign First Aligners - Invisalign First Palatal Expander - Vivera Retainer - Invisalign Retainer
3	Implant Planning	- Surgical guide Tooth supported - Surgical guide Tissue Supported - Surgical guide Bone supported
4	Fixed Restorative	/
5	Denture/Removable	- Partial Denture/Framework - Immediate Denture - Full Immediate Denture - Full Denture Tissue Based - Full Denture Implant Based
6	Appliance	- Night guard - Bite Splint - Sports/Mouth guard - Apnea/Sleep Appliance - Ortho Appliance

Link to iTero Viewer¶

The returned response provides a direct link to view the case in iTero 3D viewer (ViewerUrl).

Note, it is required to log in to myitero.com to see the scan (once per session).

Get Order by Rx ID¶

To retrieve the 3^rd party lab’s order for a specific Rx, use the following GET call:

Title	URL
Discovery API	{{Domain}}/{{Path}}/orders/:rxId
Legacy	{{baseUrl}}/api/third-party/v2/orders/:rxId

Header¶

Access token that is returned in pairing step Use type of ‘Bearer Token’

Path Variables¶

Key=rxId, Value=RX GUID for which the order information is requested.
RX id for example is: 4d98d830-4140-4c2e-b641-49b4d6b5bad5`

Response¶

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
400	Bad request	Wrong RXID format	Check if the RXID format is incorrect
401	Unauthorized error	1. Wrong token 2. Missing token	Double-check that the call is using the correct pairing token
404	Not found	Wrong RXID	Check if the RXID is incorrect
500	Internal Server error	/	A retry mechanism is recommended for this error message

In case of returned code of 200, the following response will be returned:

{
    "Data":{
        "ProcedureName": string,
        "ProcedureTypeName": string,
        "RxId": GUID,
        "OrderId": number,
        "OrderCode": string,
        "ScanningDate": date,
        "DoctorId": number,
        "ScanningOperatorId": number,
        "ScanningOperatorName": string,
        "ScanningTime": number,
        "PatientFirstName": string,
        "PatientLastName": string,
        "PatientChartNumber": string,
        "CaseType": string,
        "CompanyId": number,
        "CompanyName": string,
        "LabId": number,
        "LabName": string,
        "Preps":[
                {
                "AdaId": number,
                "UnitTypeId": number,
                "UnitTypeName": string,
                "BridgeId": number
                }
                ],
        "Notes": string,
        "ViewerUrl": string,
        "ThumbnailsDownloadUrl": string,
        "IdeFileUrl": string,
        "ScreenCaptureFileUrl": string,
        "Status": string,
        "DueDate": date,
        "PatientId": number,
        "DoctorName": string,
        "DoctorLicenseNumber": number,
        "Urls": {
            "MyiTero3DViewerUrl": string,
            "IDEFileUrl": string,
            "ScreenCaptureUrl": string,
            "ThumbnailsUrl": string
                },
        "ScannerModelDescription": string,
        "ScannerModelId": int 
            },
    "Status": number
}

Below is a table describing the information that has been returned in the Data section of the response:

Field	Type	Description
ProcedureName	String	Name of Procedure
ProcedureTypeName	String	Name of procedure type
RxId	GUID	Rx id for the retrieved scan
OrderId	Number	Order Id of the order
OrderCode	String	Order code of the order
ScanningDate	Date	Order’s scanning date time (Always in GMT + 0 same as MAT)
DoctorId	Number	Id of the doctor
ScanningOperatorId	Number	Id of person that performed the scan
ScanningOperatorName	String	Name of person that performed the scan
ScanningTime	Number	Duration of the scan in seconds
PatientFirstName	String	Order’s patient’s first name
PatientLastName	String	Order’s patient’s last name
PatientChartNumber	String	Order’s patient Chart number
CaseType	String	- Expanded - Full Arch - Quadrant - Reference Model - iRecord
CompanyId	Number	ID of the company that performed the scan
CompanyName	String	Name of the company that performed the scan
LabId	Number	ID of the lab that received the scan
LabName	String	Name of the lab that received the scan
Preps	List	Array of preps with their attributes, such as type of unit, tooth number etc.
Notes	String	Notes of the doctor
ViewerUrl	String	MyiTero.com 3D scan viewer URL
ThumbnailsDownloadUrl	String	URL to retrieve Thumbnails artifacts
IdeFileUrl	String	URL to retrieve STL/PLY artifact
ScreenCaptureFileUrl	String	URL to retrieve screen captures (if any)
Status	String	Order status: Ready for Download or Lab Review
DueDate	Date	Restorative orders - Expected delivery date of the product from the lab. Invisalign orders - Order creation date
PatientId	Number	Deprecated value
DoctorName	String	Name of the person that performed the scan
DoctorLicenseNumber	String	License number of the person that performed the scan
MyiTero3DViewerUrl	String	MyiTero.com 3D scan viewer URL
IDEFileUrl	String	URL to retrieve STL/PLY artifact
ScreenCaptureUrl	String	URL to retrieve screen captures (if any)
ThumbnailsUrl	String	URL to retrieve Thumbnails artifacts
ScannerModelDescription	String	Scanner model used to create the order
ScannerModelId	Int	Scanner model unique identifier

Status of the call will be 1 for a success call. Otherwise 0

Refer to Procedures and Types above for procedure types.

Note

Use the returned links to download assets. This will make sure the call does not break in case of a change in the URLs.

Callback Request¶

Scan notifications is a mechanism that implements a webhook to notify the lab that a new scan is ready. This mechanism can be used in exchange or in addition to the polling mechanism of Get Orders.

Once the model is scanned and sent to the server (Order is created), Align will POST the data regarding the Order to the callback URL that was provided as part of the pairing process (refer to ‘Authentication and Pairing Process’ document).

Info

This data will be sent only if the callback URL is provided in the pairing step.

Notification Criteria¶

A notification will be sent once the 3 listed files are ready:

Scan is available on myitero.com for view
Zip file (STL/PLY) is ready
Thumbnails artifacts are ready

Note that currently a new screen capture will not trigger a notification.

A notification for a scan will be pushed every time a scan has changed. This will happen in the following cases:

After scanning (first time, should always happen)
After modeling
After interpretation 2
After re-scan if scan is returned to the doctor

Pushed data¶

The notification includes the following information:

Id: RX ID - Scan unique identification number
CompanyId: Account ID - to which the scan is associated

The RX ID can be used to fetch an order using the call described in Prerequisites.

Account ID can help the third party software find the lab to which the scan belongs to.

If the webhook is not use, the alternative is to constantly poll the ‘get orders’ calling the API described in Dynamic Domain and Base .

Notification example:

{
 "Id": "9700b318-b89a-4004-9b74-ad9cd657c03f",
 "CompanyId": "90360"
}

Download Scan¶

Having the order ID, scan files can be retrieved for a specific order.

To retrieve an artifact, use the following GET request:

Title	URL
Discovery API	{{Domain}}/{{Path}}/order/:orderId/download/:assetType
Legacy	{{baseUrl}}/api/third-party/v2/order/:orderId/download/:assetType

Header¶

Authorization includes access token as bearer token. Headers:

{
'Authorization': 'Bearer Access Token'
}

Path Variables¶

Call parameters should include the following:

orderId:{{order_id}} ID of the requested order
assetType: {{assetType}}

Asset type is one of the following:

IMAGE_GALLERY – for thumbnails
IDE – for STL/PLY file
SCREEN_CAPTURE - for screen captures

Info

A link to screen captures is provided regardless if screen captures were taken. The call will return error code 204 (no content) in case no captures are available. However, screen captures can be taken at any time after the scan is completed, so if taken in a later time, they will be available for download using this API.

Response¶

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
204	No content	There are no 3D files or screenshots created for the order	/
400	Bad request	Wrong asset format	Double-check that the call is using the correct asset name
401	Unauthorized error	1. Wrong token 2. Missing token	Double-check that the call is using the correct pairing token
404	Not found	1. Wrong orderid 2. Wrong asset type 3. 3D/iDE file is not yet ready	This error code will trigger the generation of the 3D file (iDE) if not generated; Therefore, a retry mechanism is recommended. Make sure to wait enough time as the file generation takes around 1 min.
500	Internal Server error	/	A retry mechanism is recommended for this error message.

In case of returned code of 200 the file will be downloaded successfully.

Downloaded Artifacts¶

All artifacts types are downloaded in a zip format.

Asset Type	Notes	Artifacts
iDE	3D file, generated by the format selected by the user in Export Settings (in myitero.com)	- 3D files (STL/PLY) - RX in HTML format - Scan metadata in XML format - Thumbnails for ortho case
IMAGE_GALLERY	Also called thumbnails.	Six photos (JPG) of the scan of different views
SCREEN_CAPTURE	A link to screen captures is provided regardless if screen captures were taken. The call will return error code 204 (no content) in case no captures are available. Screen captures can be taken at any time after the scan is completed (from the scanner or in myitero.com), so if taken at a later time, they will be available for download using this API.	- Entire scanner window - 3D image - 2D NIRI image (iTero Element 5D only) - 2D color image (iTero Element 5D only)

Export Format¶

A file will be converted to the format that is selected by the lab on myitero.com:

Export Settings

If changing the Export Format, the change will apply to all cases downloaded from this point on, including old cases.
In order to download a scan in a different format, it can be done from myitero.com.
A third party can choose to select export settings to be applied to all clinics that are part of the integration. In case it is used, it will not be reflected on myitero.com.
Export format must be defined in order to get the cases from the integration unless it is applied by the 3^rd party (no defaults are configured).

Return Scan¶

To return a scan back to clinic use the PATCH call:

Title	URL
Discovery API	{{Domain}}/{{Path}}/order/:orderId/return
Legacy	{{baseUrl}}/api/third-party/v2/order/:orderId/return

Header¶

Authorization includes Access Token as bearer token. Headers:

{
'Authorization': ‘'Bearer Access Token’
}

Path Variables¶

OrderId – ID of order that is returned.

Request body¶

Body should include a reason code and a free text describing the return reason.

Reason codes are:

Margin line
Missing scan
Missing bite
Other :

{
"Reason": reasonCode,
"Note": "Reason - free text"
}

Info

An order can be returned in the following conditions:
- Scan was performed in the past seven days
- Scanner software version is 1.9 and up

Order's returned, and then received again, maintain the same OrderID.

The API doesn't keep a history of the previous versions, only the current version is available for download.

Info

Doctor's point of view. When a scan is returned to the doctor, it will appear under the doctor's orders, at the top with Status 'Returned', like in the examples below.

Additionally, the return reason can be seen in the order's Rx. under the 'Notes' tab.

Returned Order

Send Scan to Modeling¶

A lab can choose to send a scan to modeling after receiving the scan from the clinic. A modeler technician will review the scan and make the necessary improvements.

To send a scan to modeling use the PATCH call:

Title	URL
Discovery API	{{Domain}}/{{Path}}/order/:orderId/back-to-modeling
Legacy	{{baseUrl}}/api/third-party/v2/order/:orderId/back-to-modeling

Header¶

Authorization includes Access Token as bearer token :

{
'Authorization': ‘Bearer Access Token’
}

Path Variables¶

OrderId - ID of the order that will be sent to modeling

Request body¶

The body section will be made up of:

{
  "Reason": "",
  "Note": ""
}

Note that we do not have specific restricted values for this fields, you can place a character string with all the necessary information.

Important

An order can be sent to modeling in the following conditions:

- Procedure = Fixed Restorative

- Order Status = Ready for Download / Lab Review / Downloaded

LMS

Definitions, Acronyms, Abbreviations¶

Lab Connector API Overview¶

Dynamic Domain and Base URL¶

Prerequisites¶

Lab Connector Endpoints¶

Get Orders¶

Listed cases¶

Header¶

Query Parameters¶

Response¶

Procedures and Types¶

Link to iTero Viewer¶

Get Order by Rx ID¶

Header¶

Path Variables¶

Response¶

Callback Request¶

Notification Criteria¶

Pushed data¶

Download Scan¶

Header¶

Path Variables¶

Response¶

Downloaded Artifacts¶

Export Format¶

Return Scan¶

Header¶

Path Variables¶

Request body¶

Send Scan to Modeling¶

Header¶

Path Variables¶

Request body¶

Verify CAPTCHA