DPMS

iTero DPMS API enables third party users to create RXs using their own software, in addition to using an iTero scanner or myitero.com.

RX can be sent to iTero scanner to speed up patient visits and avoid unnecessary mistakes. Upon scan completion, the scan is available for the office DPMS.

Thanks to secure authentication, filling iTero credentials will be required one time only during the pairing process.

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
DPMS	Dental Practice Management System
DMPS Software / (ScanRequestPartner)	DPMS software company
DPMS User / (ScanRequestClient)	Specific doctor/clinic using the DMPS software
GUID	Globally Unique Identifier
Callback URL	URL to which a notification is sent upon scan completion

DPMS Overview

DPMS set of APIs includes the following:

• Get Practice Configuration
• Scan Request
• Delete RX
• Callback Request
• Get Orders for Practice
• Get Order by RX ID
• Download Scan

Dynamic Domain and Base URL

To offer a robust and flexible solution, the domain and path of all endpoints are returned to the caller through the endpoint "Discovery"

The caller should use these returned values rather than hardcoding them. 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 Process V2" specification.

All response bodies are in JSON format.

Prerequisites

Authentication and pairing must be completed before calling DPMS API, resulting with:

• access_token
• refresh_token

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

DPMS Endpoints

Get Practice Configuration

Use this call to retrieve practice information prior to calling scan request (refer to Scan Request). The practice information that is returned is required as input for scan request API.

To retrieve practice information, use the following GET call:

Title	URL
Discovery	{{Domain}}/{{Path}}/practice-configuration
Legacy	{{baseUrl}}/api/third-party/v2/practice-configuration

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’.

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 is recommended for this error message

A JSON file containing details of the practice is returned. A list of the case type codes is displayed below the file.

{
 "Data": {
  "Header": {
   "CompanyId": number,
   "CompanyName": string,
   "CountryCode": string,
   "ReportDate": date
  },
  "Doctors": [
   {
    "Id": number,
    "Name": string
   },
   {
    "Id": number,
    "Name": string
   }
   ..
  ],
  "Labs": [
   {
    "Id": number,
    "Name": "string",
    "Types": [
     "Dental",
     "Ortho"
    ],
    "Address": "string",
    "DefinedCaseTypes": [
     number,
     number
    ]
   },
   {
    "Id": number,
    "Name": "string",
    "Types": [
     "Dental",
     "Ortho"
    ],
    "Address": "string",
    "DefinedCaseTypes": [
     number,
     number
    ]
   }
   ...
  ],
  "UnitTypes": [
   {
    "Id": number,
    "Name": string
   },
   {
    "Id": number,
    "Name": string
   },
  ],
 },
 "Status": 1
}

The table below lists the returned fields in Data section:

Field	Type	Description	When to use
CompanyId	Number	ID of the paired account	Scan Request
CompanyName	String	Name of the paired account	Requires to keep data updated
ReportDate	Date	Current date	Requires to keep data updated
Doctors	List	List of doctors associated with the account ID Number System ID of doctor Name String Name of the doctor SupportedCaseTypes List of numbers List of codes for supported case types	Scan Request
Labs	List	List of labs related to the account ID Number System ID of the lab Name String Name of the lab Types List of types Options are: • Dental (which is restorative) • Ortho Address String Lab address DefinedCaseTypes List of supported case types List of case types supported by the lab. This field is for backwards compatibility	DPMS can use this list to know from which labs to expect cases to arrive
UnitTypes	List	List of unit types supported by the clinic ID Number Code for unit type Name String Name of unit type	Deprecated

A status of 1 is returned upon success.

Unit Types

The following table lists the unit types:

Unit Type Code	Unit Type
1	Regular
2	Crown
3	¾ Crown
4	Implant Abutment
5	Inlay
6	Onlay
7	Veneer
8	Detachable
9	Missing (edentulous space)
10	Missing (no spaces)
11	Deciduous
12	Scan body
13	CerecGuide

Scan Request

This call allows the caller to push an RX to the company’s scanner(s).

To initiate a scan request, use the following POST call:

Title	URL
Discovery	{{Domain}}/{{Path}}/scan-request
Legacy	{{baseUrl}}/api/third-party/v2/scan-request

The call serves two purposes:

1. Push RX to scanner - Send RX with patient details and desired procedure to the scanner. Clinical information will be filled out on the scanner.
2. Update patient's details. This is available only if the integration is configured to allow it Patient Management calls.

Notes:

• If patient does not exist in the scanner’s list of patients a new entry will be added.

• Criteria for matching a patient is:

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

In case a patient with all three fields matching exists in the system, the RX will be associated with this patient. If not, a new one will be created.

• If integration is configured to allow patient details update, the caller can update patient first name and/or last name based on matching chart number. If there are more than one patients with the passed chart number, the function will fail with error code 409. Refer to the error codes below.

• Once a patient 'date of birth' is stored, a 'Scan request' would not update the same patient with another date of birth value.

• If NIRI is available, the generated RX will honor the account's NIRI settings

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’.

Response

The scan request returns the Rx ID, as a GUID.

This Rx ID can be used to get an order by Rx.

The table below describes the optional codes returned by the API:

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	Example: { "Data": "a09292aa-8b06-45f9-a73c-350538bb32f3", "Status": 1 }
400	Bad request	1. Wrong DoctorId 2. Wrong data format	Double-check if the data format is correct
401	Unauthorized error	1. Wrong token 2. Missing token	Double-check that the call is using the correct pairing token
409	Conflict	More than one patient is found with the passed chart number. The operation does not go through. This error code is available only if the account is configured to allow patient's details update.	Double-check if there is duplicate chart number for different patient in system. Check with iTero if the update is enabled
500	Internal Server error	/	A retry mechanism is recommended for this error message

Supported format for body is raw using Json only.

{
  "CompanyId": number,
  "DoctorId": number,
  "LicenseNumber": string,
  "PatientFirstName": string,
  "PatientLastName": string,
  "PatientChartNumber": string,
  "Gender": integer/string,
  "DateOfBirth": string/date,
  "Notes": string,
  "labId": number,
  "procedureMapId": number

}

Below is a table describing the request fields:

Field	Type	Is mandatory	Description
CompanyId	Number	Yes	ID of account
DoctorId	Number	Yes	ID of the doctor
LicenseNumber	String	No	Doctor’s license number. If sent, the doctor's license number will be updated for this RX and on. If empty, the current license number will be used.
PatientFirstName	String	Yes	Patient’s first name
PatientLastName	String	Yes	Patient’s last name
PatientChartNumber	String	Yes	Patient Chart Number or Medical Record Number (MRN)
Gender	String/Number	No	Patient's gender. Use either: “Male”/”Female” or 109 (for male)/102 (for female)
DateOfBirth	Date/Time	No	Patient’s birth date. Optional formats: YYYY-MM-DDTHH:MM:SS.SSSZ or YYYY-MM-DD
Notes	String	No	Any free text
labId	Number	No	ID of the destination lab
procedureMapId	Number	No	ID of the desired procedure (find options below)

Procedure selection

To pass procedure, procedure type and type of destination (lab, myitero.com) use the corresponding procedureMapId.

The options for this parameter are below.

Examples:

• To select a Fixed restorative scan which is sent to a restorative lab - use procedureMapId 30

• To select an Invisalign, First Aligners scan - use procedureMapId 4

Procedure Name	Procedure Type	Send To Type	ProcedureMapID
Study Model - iRecord	N/A	Lab	1
Study Model - iRecord	iCast	No Send To	2
Study Model - iRecord	N/A	No Send To	54
Study Model - iRecord	N/A	Lab	78
Study Model - iRecord	N/A	myitero.com	80
Invisalign - Vivera	Aligners	No Send To	3
Invisalign - Vivera	First Aligners	No Send To	4
Invisalign - Vivera	First Palatal Expander	No Send To	5
Invisalign - Vivera	Vivera Retainer	No Send To	6
Invisalign - Vivera	Invisalign Retainer	No Send To	7
Implant Planning	Surgical guide Tooth supported	Lab	24
Implant Planning	Surgical guide Tissue Supported	Lab	25
Implant Planning	Surgical guide Bone supported	Lab	26
Implant Planning	N/A	Lab	44
Implant Planning	Surgical planning only - No guide	Lab	46
Implant Planning	Surgical guide Tooth supported	No Send To	59
Implant Planning	Surgical guide Tissue Supported	No Send To	60
Implant Planning	Surgical guide Bone supported	No Send To	61
Implant Planning	Surgical planning only - No guide	No Send To	64
Implant Planning	N/A	No Send To	65
Implant Planning	Surgical guide Tooth supported	myitero.com	85
Implant Planning	Surgical guide Tissue Supported	myitero.com	86
Implant Planning	Surgical guide Bone supported	myitero.com	87
Implant Planning	Surgical planning only - No guide	myitero.com	90
Implant Planning	N/A	myitero.com	91
Fixed Restorative	N/A	Lab	30
Fixed Restorative	N/A	No Send To	62
Fixed Restorative	N/A	myitero.com	88
Denture/Removable	Partial Denture/Framework	Lab	20
Denture/Removable	Immediate Denture	Lab	21
Denture/Removable	Full Denture Tissue Based	Lab	22
Denture/Removable	Full Denture Implant Based	Lab	23
Denture/Removable	N/A	Lab	48
Denture/Removable	Partial Denture/Framework	No Send To	57
Denture/Removable	Immediate Denture	No Send To	58
Denture/Removable	Full Denture Tissue Based	No Send To	70
Denture/Removable	Full Denture Implant Based	No Send To	71
Denture/Removable	N/A	No Send To	72
Denture/Removable	Partial Denture/Framework	myitero.com	83
Denture/Removable	Immediate Denture	myitero.com	84
Denture/Removable	Full Denture Tissue Based	myitero.com	95
Denture/Removable	Full Dentrue Implant Based	myitero.com	96
Denture/Removable	N/A	myitero.com	97
Denture/Removable	Full Immediate Denture	Lab	104
Denture/Removable	Full Immediate Denture	No Send To	105
Denture/Removable	Full Immediate Denture	myitero.com	107
Appliance	Night guard	Lab	8
Appliance	Bite Split	Lab	9
Appliance	Sports/Mouth guard	Lab	10
Appliance	Apnea/Sleep Appliance	Lab	11
Appliance	Ortho Appliance	Lab	13
Appliance	Night guard	Lab	14
Appliance	Bite Split	Lab	15
Appliance	Sports/Mouth guard	Lab	16
Appliance	Apnea/Sleep Appliance	Lab	17
Appliance	Ortho Appliance	Lab	19
Appliance	N/A	Lab	41
Appliance	N/A	Lab	42
Appliance	Night guard	No Send To	55
Appliance	Bite Split	No Send To	56
Appliance	N/A	No Send To	63
Appliance	Sports/Mouth guard	No Send To	66
Appliance	Apnea/Sleep Appliance	No Send To	67
Appliance	Ortho Appliance	No Send To	69
Appliance	Night guard	myitero.com	81
Appliance	Bite Split	myitero.com	82
Appliance	N/A	myitero.com	89
Appliance	Sports/Mouth guard	myitero.com	92
Appliance	Apnea/Sleep Appliance	myitero.com	93
Appliance	Ortho Appliance	myitero.com	94

Delete RX

This call allows the caller to delete RX that was created by Scan Request.

To initiate a scan request, use the following DELETE call:

Title	URL
Discovery	{{Domain}}/{{Path}}/scan-request/:RXID
Legacy	{{baseUrl}}/api/third-party/v2/scan-request/:RXID

Deleting an RX from the DPMS removes the RX from the scanner and from myitero.com and keeps the DPMS and the scanner aligned.

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’.

Path Variables

Call parameters should include the following:

• RXID: RXID of the RX that is returned by Scan Request API

Response

The delete RX returns the Rx ID, as a GUID.

The table below describes the optional codes returned by the API:

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	Example: { "Data": "a09292aa-8b06-45f9-a73c-350538bb32f3", "Status": 1 }
400	Bad request	Wrong RXID	Double-check if the data format is correct
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 is recommended for this error message

Get Orders for Practice

To get a list of the practice orders use the following GET call:

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

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’.

Parameters

Retrieved scans can be filtered by the following parameters:

Key	Is mandatory	Description
Offset	Yes	Number of orders to skip. Orders are returned from oldest to the most recent. In order to get to the more recent orders use offset variable. Paging is implemented by the parameters Offset and pageSize together.
pageSize	Yes	Number of orders to retrieve. Maximum number is 1024
dateTo	No	Scans dated up to this date will be returned
dateFrom	No	Scans dated from this date on will be returned
chartNumber	No	Scans with the specified chart number will be returned

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 is recommended for this error message.

{
    "Data": {
        "HasMore": boolean,
        "PageSize": number,
        "Offset": number,
        "Results": [
            {
                "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": list,
                "Notes": string,
                "ViewerUrl": string,
                "ThumbnailsDownloadUrl": string,
                "IdeFileUrl": string,
                "ScreenCaptureFileUrl": string,
                "Status": string,
                "DueDate": datetime,
                "PatientId": number,
                "DoctorName": string,
                "DoctorLicenseNumber": string,
                "Urls": {
                    "MyiTero3DViewerUrl": string,
                    "IDEFileUrl": string,
                    "ScreenCaptureUrl": string,
                    "ThumbnailsUrl": string
                        },
                "ScannerModelDescription": string,
                "ScannerModelId": int
            },
            {
              (...more scans)
            }
                  ]
    },
    "Status": 1
}

Below is a table describing the information that has been 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	Orders offset to retrieve from, use 0 to get the most recent ones. Use a positive number to get older orders
Results	ProcedureName	String	Name of Procedure
	ProcedureTypeName	String	Name of procedure type
	RxId	GUID	Id of Rx
	OrderId	Number	Order Id of the order available for retrieval
	OrderCode	String	Order code of the order available for retrieval
	ScanningDate	Date	Order’s scanning date time (Always in GMT + 0)
	DoctorId	Number	Id of the person that performed the scan
	ScanningOperatorId	Number	Id of operator
	ScanningOperatorName	String	Name of operator
	ScanningTime	Number	Scanning time in seconds
	CompanyId	Number	Id of the company that performed the scan
	PatientFirstName	String	Order’s patient first name
	PatientLastName	String	Order’s patient last name
	PatientChartNumber	String	Order’s patient chart number
	CaseType	String	Case type: • Restorative • iRecord • iCast • Invisalign • Invisalign + iRecord
	CompanyId	Number	Id of performing practice
	Company Name	String	Name of performing practice
	LabId	Number	Id of lab which scan is sent to
	LabName	String	Name of lab which scan is sent to
	Preps	List	Array of preps with their attributes, such as type of unit, tooth number etc. Example: "Preps": [  {   "AdaId": 4,   "UnitTypeId": 2,   "UnitTypeName": "Crown",   "BridgeId": null  } ],
	Notes	String	Notes of the doctor, if there is no note will return with null
	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 screenshots taken for that order (if any)
	Status	String	Order status: • Completed • iTero Modeling • Lab Review • Scanning • iTero Milling • Exporting to Doctor Site • Align Production
	DueDate	Datetime	Restorative orders - Expected delivery date of the product from the lab. Invisalign orders - Order creation date.
	PatientId	Number	PatientID is a deprecated value
	DoctorName	String	Doctor's full name
	Doctor's license number	String	Doctor's license number
	Urls	String	Sub fields: MyiTero3DViewerUrl: MyiTero.com online 3D scan viewer URL IDEFileUrl: URL to retrieve STL/PLY, thumbnails, Rx, and XML file ScreenCaptureUrl: URL to retrieve screen captures (if any) ThumbnailsUrl: URL to retrieve gallery images of the scan Use the returned URLs to download assets. The full call is described in this document in Download Scan paragraph.
	ScannerModelDescription	String	Scanner model used to create the order
	ScannerModelId	Int	Scanner model unique identifier

A status of 1 is returned upon success.

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

Backwards Compatibility

iTero new RX uses Procedures and types. To keep backwards compatibly, the endpoint also returns the equivalent case type. Use case types if the received procedure is null.

Note

With iTero new RX, new procedures were introduced that don't have a matching case type. The returned case type is the best match.

Scan Status

Scans can be returned with different statuses depends on the case flow.

The following table lists the optional statuses:

Status	Stage in flow	Cases	How to handle
Completed	Case is available for download after scanning	All cases but Invisalign	Case is available for the DPMS
iTero Modeling	Case was sent to modeling by the lab	Restorative cases/cases that are sent to lab
Lab Review	Cases are back to the lab after modeling	Restorative cases/cases that are sent to lab	After modeling the order files are changed. Consider redownload
Scanning	Case is returned to the clinic by the lab	Restorative cases/cases that are sent to lab	Consider alerting the doctor if a case is back (an alert is shown on the scanner)
iTero Milling	Case was sent to milling by the lab	Restorative cases/cases that are sent to lab
Exporting to Doctor Site	Case was sent to IDS (Invisalign site)	Invisalign cases
Align Production	Status is used in various scenarios, when the case is processed.	Vary	This is a temporary status.

Note that a scan can be listed with different statues as it goes in the flow. The order ID will not change while its status will change.

Listed Orders

User can retrieve a list of clinic’s scans. The retrieved scans are orders that meet the criteria. An order will be listed when it has zip file, thumbnails and it is ready on myitero.com.

Note

In order to have the zip file ready, each user of a clinic must have export settings defined. A default is currently applied, but if a user wants different export settings, they must be modified. Selecting export settings is done in myitero.com, in settings. Below is an example for selected settings:

A third party can choose to select export settings to be applied to all clinics that are part of the integration. So all downloaded files are consistent.

Note that this is optional, and if done, it will not be reflected on myitero.com. For more information please refer to the 'Export Settings' section under 'Data Dictionary'.

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).
• In order to view scans of another doctor in the clinic, a Full Oder Visibility must be granted.Please contact iTero support.

Callback Request

Scan notifications is a mechanism that implements a webhook to notify 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 GUID of the order to the callback URL that was supplied as part of the scan request endpoint.

Note

A notification will be sent only if the callback URL is provided in pairing or if a callback URL is configured for all the users of that connection by request.

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 push notification includes:

• Id: RX ID (GUID).
• CompanyId: Account number to which the scan belongs

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

The account number can help the third party locate the account to which the scan belongs to.

If scan notification is not used, the alternative is to constantly poll the ‘get orders’ calling the API described in Get Orders for Practice.

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

Callback URL

Callback URL can be provided to Align by the third party as described in the 'Authentication and Pairing Process - V2 .

Get Order by RX ID

To get a specific scan by its Rx GUID use the following GET call:

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

This endpoint displays the same information as Get Orders for Practice. The difference is that it returns only 1 order.

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’.

Path Parameters

Pass RxID (GUID) to the call.

Response

Response codes are:

HTTP Status	Code	Description Scenario	Recommendation
200	OK	/	/
400	Bad request	Wrong RXID format	Double-check the data format
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	Double-check if the RXID is correct
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.

Response returns the details for the specific scan:

{
    "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": "list",
        "Notes": "string",
        "ViewerUrl": "string",
        "ThumbnailsDownloadUrl": "string",
        "IdeFileUrl": "string",
        "ScreenCaptureFileUrl": "string",
        "Status": "string",
        "DueDate": "datetime",
        "PatientId": "number",
        "DoctorName": "string",
        "DoctorLicenseNumber": "string",
        "Urls": {
            "MyiTero3DViewerUrl": "string",
            "IDEFileUrl": "string",
            "ScreenCaptureUrl": "string",
            "ThumbnailsUrl": "string"
                },
        "ScannerModelDescription": "string",
        "ScannerModelId": "int"
    },
    "Status": 1
}

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	Id of Rx
DoctorId	Number	Id of the doctor
ScanningDate	Date	Order’s scanning date time (Always in GMT + 0)
ScanningOperatorId	Number	Id of person that performed the scan
ScanningOperatorName	String	Name of person that performed the scan
ScanningTime	Number	Number of seconds of scan
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	Case type: • Restorative • iRecord • iCast • Invisalign • Invisalign + 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, if there is no note will return with null
ViewerUrl	String	MyiTero.com 3D scan viewer URL
ThumbnailsDownloadUrl	String	URL to retrieve STL/PLY artifact
IdeFileUrl	String	URL to retrieve Thumbnails artifacts
ScreenCaptureFileUrl	String	URL to retrieve screen captures (if any)
Status	String	Order status: • Completed • iTero Modeling • Lab Review • Scanning • iTero Milling
DueDate	Datetime	Restorative orders - Expected delivery date of the product from the lab. Invisalign orders - Order creation date.
PatientId	Number	PatientID is a deprecated value
DoctorName	String	Doctor's full name
DoctorLicenseNumber	String	Doctor's license number
Urls	String	Sub fields: MyiTero3DViewerUrl: MyiTero.com 3D scan viewer URL IDEFileUrl: URL to retrieve Thumbnails artifacts ScreenCaptureUrl: URL to retrieve screen captures (if any) ThumbnailsUrl: URL to retrieve STL/PLY artifact
ScannerModelDescription	String	Scanner model used to create the order
ScannerModelId	Int	Scanner model unique identifier

Status of the call will be 1 for a successful 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.

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	{{Domain}}/{{Path}}/order/:orderId/download/:assetType
Legacy	{{baseUrl}}/api/third-party/v2/order/:orderId/download/:assetType

Header

Access token that is returned in pairing step

Use type of ‘Bearer Token’

Path Variables

Call parameters should include the following:

• orderId: ID of the requested order
• assetType: Asset type is one of the following:
• IMAGE_GALLERY – for thumbnails
• IDE – for STL/PLY file (along with thumbnails and metadata)
• SCREEN_CAPTURE - for screen captures

Note that 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 at a later time, they will be available for download using this API.

Response

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	File was downloaded successfully	/
204	No content	There are no screenshots created for the scan	/
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 call is using the correct pairing token
404	Not found	1. Wrong orderid 2. Wrong asset type 3. 3D/iDE file 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 time varies around 1-2 minutes.
500	Internal Server error	/	A retry mechanism is recommended for this error message.

Downloaded Artifacts

All artifact types are downloaded in a zip format.

Asset Type	Notes	Artifacts
iDE	3D file format meets the selected format by the user	• 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 in 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 scan will be converted to the format that is selected by the doctor on myitero.com (the selection is individual per user):

• If changing the Export Format, the change will apply to all cases downloaded from this point on, including old cases.

• Downloading a scan in a different format 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. In order to do it please contact iTero Professional Services, or iteroapisupport@aligntech.com

Default Export Settings

If no export settings are selected, the scan files will be generated by default settings:

Parameter	Default Value
Export Type iCast	Solid Model with Low Profile Base
Export Type iRecord	Solid Model with Low Profile Base
Data Format	File per arch (each arch with teeth up)
File Type	STL
CAD CAM System	Color Export Open Model

Hide Patient Name

Patient name can be hidden from metadata file (XML) if selected. It will appear in the metadata returned by the API calls of 'Get Orders for Practice' (4.4) and get order by RxID (4.5), but will be removed from the metadata that is downloaded with the 3D file.

Hiding a patient name is done from myitero.com in the 'Export Settings' window:

Each doctor has to select this option to apply it to his orders.

Get List of Screen Captures

To get a list of screen captures use the following GET call:

Title	URL
Discovery	{{Domain}}/{{Path}}/latest-files
Legacy	{{baseUrl}}/api/third-party/v2/latest-files

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’.

Path Variables

The returned list can be filtered by date.

Key	Is Mandatory	Description	How to Use
dateFrom	No	Scans dated from this date on will be returned.	dateFrom=YYYY-MM-DD
			If no date is passed, the call will return a list from the past 14 days.
			If a time span of more than 90 days is passed, the call will return the data for the past 90 days.

Response

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

In case of returned code of 200 the file is downloaded successfully.

{
  "Data": {
    "Since": "YYYY-mm-DDTHH:MM:SSZ",
    "CompanyId": number,
    "OrderFileUrls": [
      {
        "OrderId": string,
        "Urls": {
          "SCREEN_CAPTURE": [
            {
              "FileUrl": URL,
              "CreatedDate": "YYYY-MM-DDTHH:MM:SS.SSSZ"
            },
            {
              "FileUrl": URL,
              "CreatedDate": "YYYY-MM-DDTHH:MM:SS.SSSZ"
            }
          ]
        }
      },
      {
        "OrderId": string,
        "Urls": {
          "SCREEN_CAPTURE": [
            {
              "FileUrl": URL,
              "CreatedDate": "YYYY-MM-DDTHH:MM:SS.SSSZ"
            },
            {
              "FileUrl": URL,
              "CreatedDate": "YYYY-MM-DDTHH:MM:SS.SSSZ"
            },
            ...
          ]
        }
      }
      ...
    ]
  },
  "Status": 1
}

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

Tag	Type	Description
Since	Date	The date from which the data is returned
CompanyId	Number	ID of the company that owns the assets
OrderFileUrls		List of assets by order ID
	String / OrderId	ID of the order
	String / Urls	An array of available assets for the Order ID
	String / SCREEN_CAPTURE	Label for the assets type
	String / FileUrl	Link to download the asset
	Date / CreatedDate	Creation date of the asset

A status of 1 is returned upon success.

Download Single Screen Capture

In order to use this endpoint, a call to 'Get List of Screen Captures' is mandatory to know the specific screenCaptureID.

To download asset use the following GET call:

Title	URL
Discovery	{{Domain}}/{{Path}}/order/:orderId/download/SCREEN_CAPTURE/:screenCaptureID
Legacy	{{baseUrl}}/api/thirdparty/v2/order/:orderId/download/SCREEN_CAPTURE/:screenCaptureID

Note that the full zip of screen captures can be downloaded using 'Download Scan' passing 'SCREEN_CAPTURE' to the call. Downloading specific screen captures can be done using this call.

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’.

Path Variables

Call parameters should include the following:

• orderId: ID of the requested order
• screenCaptureID: screenCaptureID that was returned in the 'Get List of Screen Captures' call

Note

Please use the full return path from 'Get List of Screen Captures'. This will assure compatibility in case changes are made to the base URL in later calls.

Downloaded Artifacts

The desired JPG photo will be downloaded.

Patient Management API

Set of APIs that allow a DPMS to perform operations to patients belonging to a practice. It is enabled by request from the integration partner.

This set of APIs includes the following:

• Patient Search
• Patient Details Update by Patient ID
• Patient Details Update by Chart Number
• Scan Request with Update
• Pairing Enhancement

Patient Search

Use this call to search for patients that match the following 2 criteria:

• First name and last name (Exact match)
• Chart number

The 2 criterions are mandatory.

The call returns zero to multiple entries as shown in the example below:

Description	Send	API returns
Pass first name, last name and chart number. API returns all entries that meet one of the following: 1. First + last names match 2. Chart number match 3. First name, last name and chart number match	John Doe 123	John Doe 123 John Doe 333 Mike Barlowe 123
Since the 2 search criteria are mandatory, if you don't send the chart parameter in the call, the endpoint will assume you are searching for a blank chart number.	John Doe	John Doe 123 John Doe Mike Caddel Steve Laurier
The practice should fix users who have the same chart number to avoid confusion. This is an example where you only send chart number	567	John Whitlock 567 Steven Doe 567

To search patient, use the following GET call:

Title	URL
Discovery	{{Domain}}/{{Path}}/patient/search
Legacy	{{baseUrl}}/api/third-party/v2/patient/search

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’

Query Parameters

Parameter	Type
firstName	String
lastName	String
chartNumber	String

Response

A JSON response containing the matching entries is returned

[
  {
    "UniqueId": "string",
    "DateOfBirth": "Date/Time",
    "Gender": "1 for female, 0 for male",
    "ChartNumber": "String",
    "FirstName": "String",
    "LastName": "String"
  },
  ...
]

UniqueId is a GUID of the patient that should be used in the following API to update patient's details.

Patient Search - V3

Use this call for enhanced patient search.

Note

Using V3 endpoints requires using V3 discovery API.

The endpoint returns a list of patients associated with the paired clinic that match the criteria passed in the filters.

Notes:

• If no filtering criteria is passed, all patients will be returned.
• Multiple filters are treated with AND operation.
• Wildcard search using * or % is allowed.
• The results are limited to 100 per call

To search patient, use the following GET call:

Title	URL
Discovery	{{Domain}}/{{Path}}/patients/search
Legacy	Not Availalbe
Version	3

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’

Query Parameters

Parameter	Type	Mandatory	Default	Notes
Offset	Integer	No	0	Manage pagination. Offset sets the index of the start entry.
Limit	Integer	No	100	Number of entries to return (100 is the maximum entries allowed per page).
FirstName	String	No		Patient name. Can use wildcard.
LastName	String	No		Patient last name. Can use wildcard.
ChartNumber	String	No		Patient chart number. Can use wildcard.
UpdatedDateFrom	Date	No		Patients with updated date later (or equal) than this date. Updated date will be changed upon update of: First Name Last Name Chart number Date of birth Gender
UpdatedDateTo	Date	No		Patients with updated date earlier than this date. Updated date will be changed upon update of: First Name Last Name Chart number Date of birth Gender
LastScanDateFrom	Date	No		Patients' last scan later (or equal) than this date.
LastScanDateTo	Date	No		Patients' last scan earlier than this date.

Response Body

{
    "Data": [
        {
            "Id": guid,
            "FirstName": String,
            "LastName": String,
            "ChartNumber": String,
            "DateOfBirth": date,
            "Gender": String,
            "CreationDate": date,
            "UpdatedDate": date,
            "LastScanDate": date
        },
        ...
    ],
      ],
    "Meta": {
        "Total": integer,
        "Count": integer,
        "NextOffset": integer
    },
    "Links": {
        "Self": "/third-party/v3/patients/search?Offset=0&Limit=100",
        "Next": "/third-party/v3/patients/search?Offset=100&Limit=100"
    },
    "Status": "Success"
}

Below is a table describing the returned information of the response: Section: Data

Field	Type	Description
Id	GUID	Unique identifier of a patient
FirstName	String	Patient's first name
LastName	String	Patient's last name
ChartNumber	String	Patient's chart number
Gender	String	"Male" or "Female" if exists. Otherwise, null
DateOfBirth	Date	Patient's birth date if exists. Otherwise, null
CreationDate	String	Patient's creation date if exists. Otherwise, null
UpdatedDate	String	Patient's update date if exists. Otherwise, null
LastScanDate	String	Patient's last scan date if exists. Otherwise, null

Section: Meta

Field	Type	Description
Total	Integer	Total number of patients meeting the search criteria
Count	Integer	Number of entries returned
Next offset	Integer	Offset to use in the next call (current offset + limit)

Section: Links

Field	Type	Description
Self	URL	Call to the same endpoint with the same parameters
Next	URL	Get the next batch for the same call
Prev	URL	Get the previous batch for the same call

Section: Status

Field	Type	Description
Status	String	Success or error code

Response Code

HTTP Status Code	Description	Scenario	Recommendation
200	OK	—	—
401	Unauthorized error	Wrong token / Missing token	Double-check that the call is using the correct pairing token
400	Bad Request	Wrong passed parameters	Fix or remove passed parameters and call again
404	Not Found	No matches	Extend filtering
500	Internal Server Error	/	A retry mechanism is recommended for this error message

Example for error 400

{
    "Status": 2,
    "Message": "Invalid request parameters",
    "Code": "INVALID_REQUEST_PARAMETERS",
    "Errors": [
        {
            "Field": "LastScanDateTo",
            "Message": "The value '2024-01-1199' is not valid for LastScanDateTo."
        }
    ]
}

Patient's Details Update by Patient ID

This call should follow the case of multiple entries returned for Patient Search.

To update patient's details use the following PATCH call:

Title	URL
Discovery	{{Domain}}/{{Path}}/patients
Legacy	{{baseUrl}}/api/third-party/v2/patients

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’

Body

{
  "PatientId": "00000000-0000-0000-0000-000000000000",
  "ChartNumber": "string",
  "FirstName": "string",
  "LastName": "string"
}

Field	Description	Mandatory
PatientId	Patient GUID returned from Patient Search For example: 8683e5e5-a9fe-47ff-96e8-2bd9aab41d23	Yes
ChartNumber	Chart number to set for patient	One or more should be set according to the Boolean value that is passed in the "Has_" parameters.
FirstName	First name to set for patient	One or more should be set according to the Boolean value that is passed in the "Has_" parameters.
LastName	Last name to set for patient	One or more should be set according to the Boolean value that is passed in the "Has_" parameters.

Response Body

{
  "LastScanDate": null,
  "RowStatus": 1,
  "DateUpdated": "2021-04-25T19:40:58.0110489Z",
  "Type": 0,
  "AlignPatientId": null,
  "Id": 0,
  "UID": "8683e5e5-a9fe-47ff-96e8-2bd9aab41d23",
  "FirstName": "string",
  "LastName": "string",
  "ChartNumber": "string",
  "DateOfBirth": "yyyy-mm-ddThh:MM:ss.MMM",
  "Gender": "1 for female, 0 for male",
  "MI": null,
  "ZipCode": null
}

Response Code

Code	Description	Notes
200	Success	Success
400	No update required	No parameter for update is passed, or patient's GUID is not found
404	No Content	Missing patient's GUID
500	Internal server error

Patient's Details Update by Chart Number

Use this call to update patient's details base on patient's chart number. This is useful for patient name changes or typos.

To search patient, use the following PATCH call:

Title	URL
Discovery	{{Domain}}/{{Path}}/patient/by-chart-number
Legacy	{{baseUrl}}/api/third-party/v2/patient /by-chart-number

Headers

Access token that is returned in pairing step.

Use type of ‘Bearer Token’

Request Body

Request body includes the chart number by which the patient is searched and the new patient's details:

{
  "ChartNumber": "String",
  "FirstName": "String",
  "LastName": "String",
  "DateOfBirth": "Date/Time",
  "Gender": "Female or Male"
}

Field	Description	Mandatory
ChartNumber	Patient's chart number	Yes
FirstName	Patient's first name	At least one value is mandatory. Pass one or more.
LastName	Patient's last name
DateOfBirth	Patient's date of birth using format of: YYYY-MM-DDTHH:MM:SS.mmm For example "1989-04-13T19:45:40.339Z" or "1989-04-13"
Gender	Patient's gender: "Female" or "Male" or integer: 0 for Male, 1 for female

Response

Response for the call returns one of the following values:

Code	Description	Notes
200	Successful update
400	Invalid request	Invalid request in case of: • Missing chart number • Missing all other fields (should pass at least one of FirstName, LastName, DateOfBirth, Gender)
404	No patient with the passed chart number is found
409	More than one patient with the passed chart number is found. The list of matching patients will be returned.	[ { "Id": 12345, "UID": "4197c230-74dc-4067-8b61-911146457588", "FirstName": "First", "LastName": "Last", "ChartNumber": "abc1", "DateOfBirth": "1980-11-12T00:00:00", "Gender": 0, "MI": 1, "ZipCode": null, "CompanyId": 18388, "DoctorId": 42556, "LastScanDate": "2021-02-01T16:01:26" }, { (...Additional Patients) } ] Note: Gender returns 1 for female, 0 for male
500	Internal server error

Scan Request With Update

This is the same endpoint listed in this document as 'Scan Request' .

As Scan Request creates a patient in iTero system, a configuration for a connection can help avoiding creating patients duplication of patients.

A patient is created according to the following rules:

• If patient does not exist in the scanner’s patients list, a new entry will be added. Criteria for matching a patient is:

  o First name

  o Last name

  o Chart number

In case a patient with all three fields matching exists in the system, the RX will be associated with this patient.

• If integration is configured to allow patient details update, the caller can update patient first name and/or last name based on matching chart number. If there are more than one patient with the passed chart number, the function will fail with error code 409 (Multiple entries are found).

Pairing Enhancement

When pairing API is called a warning will be returned in case the system finds multiple patients sharing the same chart number or there are patients missing chart number.

This allows the clinic to run housekeeping before starting to use the DPMS integration. This is a one-time effort that will pay off in the future.

For more details about pairing please refer to the Authentication Specification.

{
  "Data": {
    "OAuthResponse": ...,
    "Warnings": [
      "Empty or duplicate patient identifiers (chart#) exists in & iTero patient database"
    ],
    "CompanyId": number
  },
  "Status": 1
}