Web Service

From HostedSuite Wiki :: Evo Technologies

Jump to: navigation, search

Contents

Introduction

The HostedSuite Web Service is an HTTP based API that allows you to perform the most common HostedSuite actions using the programming language of your choice.

You can view all of the available operations on the following page:

https://evo.hostedsuite.com/api/metadata

Please note that the web service CANNOT be used for telephony "phone system" integration. It is used for database management (e.g. adding clients), scheduling, and accessing call records. Not to support new phone systems

Basics

In the image below you will see the listing of operations that the web service supports.

Ws-ops.png

While the service layer that we use supports XML, JSON, CSV, and SOAP, we only support JSON

The other protocols are not disabled, but we do not provide direct support for them either. The auto docs provide examples of calling into the API using these other protocols, but we still recommend that you use JSON

Authentication

Every request to the API is a POST with a JSON body. There are three fields that are required on every single request for authentication

CustomerName, UserName, and Password

The HostedSuite API uses the same permission structure as the HostedSuite web site, so you can use the same user names and passwords on the API as you login with.

Please note that we do NOT support authenticating to the API with a Client level login

The HTTP Request

Let's show how an example request would look using an HTTP tool so that you can see how authentication works and also how the HTTP request should be structured

Open up the ListClients endpoint from the auto docs (https://evo.hostedsuite.com/api/json/metadata?op=ListClientsRequest)

Ws-list-clients.png

URL Structure

The first thing you will notice at the top of the page is that it shows

POST /api/clients

Every single HTTP request is going to be a POST and the path after is the relative path where you will post to

The full URL in this case would be https://evo.hostedsuite.com/api/clients

If this was the ListContacts endpoint, it would be https://evo.hostedsuite.com/api/contacts

Note: at the bottom of the auto docs pages, the examples show a different URL structure, e.g. POST /json/reply/ListClientsRequest HTTP/1.1 - This will also work and the full URL would be https://evo.hostedsuite.com/api/json/reply/ListClientsRequest

Your URLs will always start with https://evo.hostedsuite.com/api

Parameters

If you look at the top of the auto docs for each request, you will see a bunch of parameter definitions, for example, ClientId, Name, CenterId and then below that in a separate group, CustomerName, UserName, Password

The reason why they are grouped like that is due to how our service backend handles the API, but all the fields shown can be used.

NOTE: The REQUIRED field is NOT always accurate. If you run into any issues contact us directly at support@evo.tech

Sample POST

The following image shows a sample POST made to the endpoint for the customer "EVO" (our test customer)

Ws-fiddler.png

Please note a couple of important parts

  1. The Content-Type header is set to application/json
  2. The Accept header is set to application/json
  3. The request body is a full JSON object with quoted identifiers

In this case the request did not specify any optional parameters, however if I wanted to filter by center for example, the request might look like this:

Ws-fiddler2.png

Date and Time

Date Times are always sent as strings to the web service. They can be specified in a few different formats but the easiest is to specify it in center relative time. For example

{ ... "StartTime" : "1/1/2019 8:00AM" }

This will be interpreted in the same time zone as the location where the center is ("local" time)

You can also specify your time in ISO 8601 if you prefer, e.g.

{ ... "StartTime" : "2008-09-15T15:53:00+05:00" }

IDs

A lot of the API requests take an ID parameter, e.g. when you want to update a Client or Contact.

In general, the ID field will already have been retrieved from a previous API call, however you can also get the IDs directly from the web interface. For example if I needed the ID to a client, I can go to the client's EDIT page and grab it from the address bar

Ws-ids.png

IDs are always specified as strings, e.g.

{ ... "ClientId" : "4fa2e08d0117b10f7c6801d9" }

Troubleshooting

Authentication

The most common problems with the API are authentication issues.

In order to verify that your authentication is correct, we first recommend you login to the HostedSuite portal with the user/pass that you are trying to use

The URL you will login at is based on your CustomerName, for example, if your CustomerName is "abc" your login url will be https://abc.hostedsuite.com

Once you have verified that your credentials are valid, we recommend you start with the simplest API request possible by copying everything in this screenshot and replacing your user/pass/customer name

Ws-fiddler.png

Assuming your login credentials are valid, the above request with your parameters should always succeed. Then it's just a matter of switching the URL/parameters to be whatever API you are trying to call.


HTTP Headers

The second most common problem is not including the Content-Type and Accept headers in your request. Both of these headers need to be specified and they should be set to application/json as shown in the above request

JSON formatting

Another common problem with the API is not using quoted identifiers. Although technically invalid, most environments allow JSON specified such as

{ CustomerName: "evo", UserName: "admin" }

This will not work with the API, the identifiers need to be quoted such as

{ "CustomerName" : "evo", "UserName" : "admin" }
Personal tools
Namespaces
Variants
Actions
Navigation
Topics
Toolbox