Introduction to EMS Platform Services

Platform Services provides RESTful APIs that empower customers and partners to build custom, multi-platform applications connected to EMS. Any client/device accessing EMS Platform Services must be a registered Integration Client. The one exception is that anyone can access the public (open) API requests (/status, /health, /clientauthentication).

There are two types of Integrations:

• Custom – Customer applications

• Partner – Third-party EMS partner applications (e.g., 7PointsSolutions, Pepperdash, control concepts, etc.)

Partner and Custom types can be classified as either of these two client subcategories:

1. User-based – User-based clients (EMS for Outlook) need to authenticate as a user to perform any actions. These clients need an integration client role with minimal access to the following API resources (above and beyond public resources):

   • /authentication

   • /logging

2. Non-user Based – Non-user Based clients (EMS Kiosk, EMS Room Sign App) provide functionality independent of users but also support user-like functionality (such as Check-In and on-the-fly room reservations). These clients need a role with wider access.

1. Verify if you have a license for adding Integrations. EMS Licensing manages a numeric count of both Custom and Partner Integration Types. Contact your EMS Sales Representative for a license for EMS Platform Services. View Licensing Requirements. 

2. Access Platform Services documentation (for example: https://Yourcompany.com/EmsPlatform/swagger). 

3. Access admin portal for Platform Services (for example: https://Yourcompany.com/EmsPlatform/admin) to create a new Integration Client.  

   A Client ID and Secret pair will be generated.

4. Platform Services requires a valid JWT Authentication token to call any of the API resources with the exception of /public, /status and /clientauthentication. Before making any API request, you must first call /clientauthentication with a Client ID and Secret pair generated in the previous step.

   • The Client token returned from calling /clientauthentication should be applied to the x-ems-api-token header for subsequent API requests.

     There can be multiple active instances of a particular client interacting with the Platform. All devices that share a client/secret will share a common authentication token. If the token expires, all devices will need to authenticate again to get a new shared token.

5. For API resources that require an authenticated web user, your integration client will need to request a web user authentication token for that user. To acquire an authentication token, call the /authentication requests.

6. The Web token returned from calling /authentication should also be applied to the x-ems-api-token header. This replaces the client token with a user token.

   To determine which token to use for the header field, see API documentation.

To view the API documentation, go to the Platform Services URL (for example: https://Yourcompany.com/EmsPlatform/swagger).

Base URL for All API Requests

Make all requests to URL for EMS Platform Services (for example: https://Yourcompany.com/EmsPlatform).

Date/Time Standards

All dates and times passed to the API requests follow RFC 3339 Standard and must be in UTC. 

All DateTimes follow the standard (e.g., 2008-09-08T22:47:31-07:00)

Common Response Codes

HTTP Request Methods