Specification

What is Scanning Tool

A scanning tool is a set of APIs that allows 3^rd parties integrating with iTero to create scans for development purposes (without a real scanner).

The Benefits of the Tool

Creating scans during development is essential for development. The tool replaces the need to assign a scanner for development purposes for iTero 3^rd parties .

The benefits of the service:

1. Self-served
2. Does not require any installation on the 3^rd party side for the development of the integration
3. Does not require allocating a scanner for the development of the integration
4. Maintained by iTero
5. Saves time for the developer that does not really need to scan

How to use

All endpoints are using the same base URL

BaseUrl: https://mate-for-partners-us-west-1-prod.iterocloud.com

The scanning tool provides 3 endpoints:

Name	Description	Type	Endpoint	Authentication
Create scan	Create and send a new case with a new RX	POST	{baseUrl}/api/v1/order/create-neworder	Basic Auth
Create scan using RXID	Create and send a new case based on an existing RX	POST	{baseUrl}/api/v1/order/create-neworder-by-rx	Basic Auth
Get Map ID	Get available Map IDs	GET	{baseUrl}/api/v1/presets/availableprocedure-maps	None

Returned Codes

APIs returned codes are described below:

HTTP Status Code	Description	Scenario
200	OK	/
400	Bad request	One of the parameters is not valid
401	Unauthorized error	1. Wrong user or password 2. Miss credentials
500	Internal Server error	/

Create Scan

Send a POST call to create a new scan.

{{baseUrl}}/api/v1/order/create-new-order

Header

Authorization: Basic auth requires a doctor user and password that were provided by the Professional Services Engineer supporting your project.

Request Body

Body includes RX information and scan procedure and type:

{
  "companyId": number,
  "scannerSerialNumber": string,
  "procedureMapId": number,
  "patient": {
    "firstName": string,
    "lastName": string,
    "chartNumber": string,
    "mi": string,
    "gender": number,
    "dateOfBirth": date,
    "zipCode": string
  },
  "notes": string,
  "labId": number
}

The table below describes the fields that are passed in the request body:

Tag Name	Type	Description	Is Mandatory
CompanyId	number	iTero ID of the doctor's clinic	Yes
ScannerSerialNumber	string	Scanner serial number of the specified clinic	Yes
ProcedureMapId	number	ID of the procedure. Refer to 'Get Available Procedure Maps'	Yes
FirstName	string	Patient's first name	Yes
LastName	string	Patient's last name	Yes
ChartNumber	string	Patient's chart number	No
Gender	number	0 - male 1 - female	Yes
DateOfBirth	date	Patient's date of birth. Format is YYYY-MM-DDTHH:MM:ss.SSSZ or YYYYMM-DD	Yes
ZipCode	string	Patient's zip code	No
Notes	string	Any free text that the scanning doctor wants to add to the RX.	No
LabId	number	iTero ID of the lab that the scan is sent to. This parameter is based on the Procedure Map ID. Map IDs that have a lab require an ID in this field. Pass null if lab is not required.	Depends

Response

Upon success of the call the API returns the following:

{
 "orderId": number,
 "orderCode": string,
 "patientGuid": GUID,
 "rxGuid": GUID (RXID)
}

The table below describes the information returned by the call:

Tag Name	Type	Description
orderId	number	A unique number assigned to the scan. This number will be used for downloading the scan's assets.
orderCode	string	A unique string assigned to the scan. This information is not required to be used by other endpoints.
patientGuid	GUID	A unique identifier of the patient
rxGuid	GUID	A unique identifier of the RX

Create scan using RXID

Send a POST call to create a scan using an existing RX.

This purpose of this endpoint is to create a scan following a "Scan Request". "Scan Request" call creates a RX that is sent to the scanner. The call returns an RXID that should be passed in this call.

{{baseUrl}}/api/v1/order/create-new-order-by-rx

Header

Authorization: Basic auth requires a doctor user and password that were provided by the Professional Services Engineer supporting your project.

Request Body

Body includes RX information and scan procedure and type:

{
 "companyId": number,
 "scannerSerialNumber": string,
 "rxId": GUID (RXID),
 "procedureMapId": number,
 "labId": number
}

The table below describes the fields that are passed in the request body:

Fields Name	Type	Description	Is Mandatory
CompanyId	number	iTero ID of the doctor's clinic	Yes
ScannerSerialNumber	string	Scanner serial number of the specified clinic	Yes
RxId	GUID	GUID of an existing RX	Yes
ProcedureMapId	number	ID of the procedure. Refer to 'Get Available Procedure Maps'	Yes
LabId	number	iTero ID of the lab that the scan is sent to. This parameter is based on the Procedure Map ID. Map IDs that have a lab require an ID in this field. Pass null if lab is not required.	Depends

Response

Upon success of the call the API returns the following:

{
 "orderId": number,
 "orderCode": string,
 "patientGuid": GUID,
 "rxGuid": GUID (RXID)
}

The table below describes the information returned by the call:

Tag Name	Type	Description
OrderId	number	A unique number assigned to the case. This number will be used for downloading the scan's assets.
OrderCode	string	A unique string assigned to the case. This information is not required to be used by other endpoints.
PatientGuid	GUID	A unique identifier of the patient
RxGuid	GUID	A unique identifier of the RX

Get Available Procedure Maps

Send a GET call to get the available Map IDs

{{baseUrl}}/api/v1/presets/available-procedure-maps

What is MapID

Each iTero case must use one of six procedures, a type (that is applicable is some of the procedures) and lab to send the case to (if applicable). Please refer to the Appendix for a list of procedures and types.

The combination of these three parameters is part of every iTero RX, and has a unique number. This number is passed when creating a case using iTero new API.

In order to know which number to pass, use the Get Available Map IDs endpoint and select one that is relevant to your flow.

Below are some common examples:

Procedure	Type	Send To	Map ID
Study Model - iRecord	NA	Ortho lab	1
Invisalign	Invisalign First Aligners	NA	4
Fixed Restorative	NA	Resto lab	30
Appliance	NA	Ortho lab	41
Denture/Removable	Partial Denture/Framework	Myitero.com	83
Implant Planning	Surgical guide Tooth supported	Myitero.com	85

Header

No authorization is required for this call

Request Body

No body is passed.

Response

Upon success of the call the API returns the following:

{
  "procedureMaps": [
    {
      "procedureMapId": number,
      "description": string,
      "note": string,
      "caseType": string,
      "procedure": string,
      "type": string,
      "sendTo": string
    },
    ...
  ]
}

The table below describes the information returned by the call:

Tag Name	Type	Description
ProcedureMapId	number	ID of the trio: Procedure, type and send To
Description	string	Description of the procedure
Note	string	How to use this Map ID
CaseType	string	For backwards compatibility, if account does not support procedures, pass the mapped case type
Procedure	string	One of 6 available procedures. Check the appendix
Type	string	Procedure type if applicable. Check the appendix
SendTo	string	Type of lab to send to. Check the appendix

Limitations

• Caller can create up to 10 cases per minute using the API
• No clinical information can be passed

Appendix

Procedures and Types

ID	Procedure Name	Type Name
1	Study Model - iRecord	- Ortho Model/iCast
2	Invisalign	- 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 Denture Tissue Based - Full Denture Implant Based
6	Appliance	- Night guard - Bite Splint - Sports/Mouth guard - Apnea/Sleep Appliance - Clear aligners - Ortho Appliance

Send To Options

Send To	Description	Details
restoLab	Case should be sent to a resto lab	Caller should provide an account number of a resto lab (LabId) that is related to the clinic account
orthoLab	Case should be sent to an ortho lab	Caller should provide an account number of an ortho lab (LabId) that is related to the clinic account
chairside	Case is sent to chair side	Caller should pass null in LabId
midc_only	Case is sent to myitero.com	Caller should pass null in LabId
N/A	No lab is involved	Caller should pass null in LabId