Getting Started

This guide will help you get started with accessing Sonova’s API using an authentication token. You will need an ID and password provided by the API administrators to obtain the token.

Prerequisites

Authentication Endpoints

There are typically two environments for accessing the API:

Steps to Obtain an Authentication Token

1. Making an Authentication Request

You will need to send a POST request to the authentication endpoint with your ID and password. Below are examples using curl.

Using Curl

curl --location --request POST 'https://b2b-s1.phonakpro.com/sonovaapi/users/token?uid=<YOUR_API_USER_ID>&password=<YOUR_PASSWORD>'

NB: Be sure to replace <YOUR_API_USER_ID> and <YOUR_API_USER_ID> parameter with the credentials provided by API administrator

2. Using the Authentication Token

Once you have obtained the token, you can use it to authenticate your requests to the API. Include the token in the Authorization header of your requests.

curl --location 'https://b2b-s1.phonakpro.com/sonovaapi/order' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \

--data '{    

    "orderHeader": {...},

    "orderItems": [...],

    "clientInfo": {...}

}'

Switching to Production

When you are ready to switch to the production environment, you will need to update the URLs in your requests accordingly:

3. Using the Refresh Token

Authentication tokens typically have an expiration time, after which they become invalid. To avoid having to log in again with your ID and password, you can use a refresh token to obtain a new authentication token.

Example Refresh Token Request using curl

curl --location --request POST 'https://b2b-s1.phonakpro.com/sonovaapi/users/token/refresh' \
--header 'Authorization: Bearer <YOUR_TOKEN>

FAQ

General notes

API return codes

Sonova API uses standard HTTP return codes.

When making HTTP requests, you can check the success or failure status of your request by using the HTTP Status Codes (i.e. 200).

Success Codes

200 OK – Request succeeded.

201 Created – Request succeeded and resource created.

202 Accepted – Request accepted for processing.

204 No Content – Request succeeded but does not return any content.

Error Codes

400 Bad Request – Parameter errors or bad method usage.

Bad usage of the resource. For example: a required parameter is missing, some parameters use an incorrect format, a data query is not in the expected state.

401 Unauthorized – API call without authentication.

Add authentication information or use a valid authentication token.

403 Forbidden – Access to the resource is denied.

Current user can not access the resource.

404 Not Found – The resource does not exist.

The resource URI or the requested resource do not exist for the current user.

405 Method Not Allowed – The HTTP method (GET, POST, PUT, DELETE) is not allowed for this resource.

Refer to the documentation for the list of accepted methods.

406 Not Acceptable – The requested response content type is not available for this resource.

Refer to the documentation for the list of correct values of the Accept header for this request.

410 Gone – The resource is permanently gone.

The requested resource is no longer available and will not be available again.

415 Unsupported Media Type – The entity content type sent to the server is not supported.

Refer to the documentation for the list of correct values of the Content-type header to send data.

429 Too many requests – Rate limits are exceeded.

The user has sent too many requests in the last hour. Refer to the documentation for the maximum calls count per hour.

500 Internal Server Error – The server encountered an unexpected error.