The API is divided into 2 areas:

The Public API does not require authentication and provides a way for applications/users to authenticate via the Public : Users endpoint.

To use the Clinic API, a user must already be authenticated. Once authenticated, a user may:

• Manage portal settings
• Manage users
• Manage patients
• Manage patient scans
• Create and monitor Otoscan packages
• View and download reports

To use the Manufacturer API, a user must already be authenticated. Once authenticated, a user may:

• Manage portal settings
• Manage users
• Manage products
• Manage order forms
• Monitor and download Otoscan packages
• View and download reports

NOTE: The API uses SSL so you will need to make sure your application servers have port 443 open in the DMZ. Additionally, the URLs for each of the endpoints below are fragments and should be preceeded with: https://.

Example: api/Reference/Countries is actually https:///api/Reference/Countries

If you have not already done so, contact your Otoscan representative and have them create an account for you. They will also create your Primary Administrator. The Primary Administrator is the user you will use to setup other Portal Administrators and Users.

Once you are able to log in to the Otoscan Portal as an Administrator, create a Portal User through the Admin section of the Portal. Make sure to not grant admin privileges to the user unless you wish to be able to change administrative settings via your application.

Once you have created your Portal User, store the username and password in a secure portion of your application.

To use the full API, you will need to authenticate via the Public : Users endpoint first: https:///api/Public/Users/Login

The API endpoints are expecting JSON objects so you will need to make sure your serializer converts your objects to JSON. For authentication you will need to POST your credentials:

The API will return your user object in JSON format and also a cookie which will contain the claims for your user. You will need to store this cookie and pass it back to the API with each subsequent request for authorization.

Once your user is authenticated, you may make a request to any endpoints for which your user is authorized. Should you attempt to access an endpoint for which you do not have a claim you will receive a 401 (Unauthorized) status code.

In order to prevent massive payloads from being transferred, the objects returned by the API do not have their children populated. Instead, they have an array of IDs for each set of children.

For example, when you call to get an Entity, the Users property will be empty, but UserIds will have an array of GUIDs which are the IDs of the Users associated with the Entity.

To get the Users, you may retrieve them by calling the .../api/{Entity}/{EntityId}/Users endpoint.

Some of the Scan files can be large (up to 12MB); in order to download these files to your application, you will need to set your max content/request length/size accordingly. Otherwise, the files may appear as nulls in your application.