Skip to main content
All CollectionsHelp CenterEmpower Your Office
Public API
Public API
Derek Deng avatar
Written by Derek Deng
Updated over 3 years ago

Anyone with Public API access enabled in their ServiceBridge account and with knowledge of software development can use the Public API to communicate with ServiceBridge accounts. 

The ServiceBridge Public API Methods can be found here: https://cloud.servicebridge.com/developer/index
​

Overview

REST Principles

ServiceBridge Public API is created using REST principles.

URLs are created using plural entity names (e.g. customers, marketingCategories) and version number (e.g. v1). These methods are supported:

  • GET for retrieve a list of entities. (e.g. GET /api/v1/customers)

  • GET for retrieve a single entity by ID. (e.g. GET/api/v1/customers/15)

  • POST for creating an entity. (e.g. POST /api/v1/customers/)

  • PUT for updating a single entity by ID. Partial and full updates are supported. (e.g. PUT /api/v1/customers/15)

  • DELETE for deleting a single entity by ID. (e.g. DELETE /api/v1/customers/15)

Request Limits

API has request limits per IP address:

  • 50 requests per second

  • 60000 requests per hour

Error Codes

When an exception occurs, error message and error code are returned.

List of error codes:

API requires TLSv1.2 with following ciphers for secure SSL/TLS handshake:

  • ECDHE-ECDSA-AES128-GCM-SHA256

  • ECDHE-RSA-AES128-GCM-SHA256

  • ECDHE-ECDSA-AES256-GCM-SHA384

  • ECDHE-RSA-AES256-GCM-SHA384

If you are getting errors that aren't listed here, confirm you are using the latest Transport Layer Security. See more details here:  https://help.servicebridge.com/en/articles/3216624-servicebridge-deprecating-support-for-tlsv1-and-tlsv1-1
​

Authentication

There are two ways to authenticate with the Public API to be able to use it: 

  1. API User 

  2. App (OAuth)

Option 1 - API User

There is a way in ServiceBridge to authenticate using API Users and sessionKeys.  To do this, you'll need to setup an API User first. 

Go to Settings → Public API Settings

Press "+ Add new". Add New API User dialog will show.

Enter details:
​Personnel. It defines what user account should be associated with the API user. In Audit History, you will see, that this user did the changes to the data. Plus, this user's access permissions will be used to grant or to forbid access to a specific data (e.g. a user can have full access to the customers' data, but have no access to the accounting data).
​API User Alias. It's the optional name that will be visible in audit history (e.g. when new customer will be created). If not provided, the system user name will be used.
​Password. In order to not share the original user password, you need to define the API user password, which will be used only to access the API methods.
​Active. If set to No, an API user account may be temporarily disabled.

When a user is created, API User Id is provided. It will be the main unique user identifier when authenticating the user:

All the methods, except Login and Logout are secured. To access these methods, a valid sessionKey GET parameter should be passed in each request (e.g. /api/v1/customers/?sessionKey=5230f77caf67d27b49dbb8f098a7d381cc7f872).

A sessionKey is generated when calling a Login method and has 30 minutes sliding expiration. It means, that on each request it's expiration is moved to 30 minutes.
​

Option 2 - Apps (OAuth)

There is also a way in ServiceBridge to authenticate via OAuth.  To do this, you'll need to setup an App. 

  1. Click on the Settings gear menu in the upper right hand corner and select 'Public API'.  Instead direct your attention to the second section under API Users called 'Apps'

  2. Select '+Add new'

3. Enter details

  • App title: your application name (it will be visible for your application users).

  • App Id: unique application identifier generated automatically by system.

  • App secret: secret code generated to your application. Together with App Id it is used to authenticate external application.

  • Redirect Uris: your client application Uris list which you allow to be redirected to. Each Uri must be on a new line.

  • Manifest Json: contains a format that defines user interface extension with additional actions to cloud.servicebridge.com and ServiceBridge Mobile App screens. As an example if you wanted to extend the Customer or Work Order screen with additional buttons that would navigate to a 3rd party application.

  • Active: if set to false, application may be temporarily disabled.

NOTE: after application disabling via Active field (change form ON to OFF), access tokens will no longer be issued within 1 minute.

Authentication

During the authentication process in your app the user will be asked:

  1. To login into the ServiceBridge account.


2. To grant your application access to ServiceBridge.

Note: if user unmarks api option - ServiceBridge API will be inaccessible.

Access Rights

ServiceBridge API access is protected by each user's unique access role defined in Personnel Settings.

That means if user has read only access to customer data, he/she will get the same read only access via API and no additional modify or delete capabilities.

The token that is received after user authorization is valid for 1 hour. If your app is intended to access user data without the user being logged in, you should obtain a refresh token (valid for 30 days), by asking the user to approve Offline access.

In ServiceBridge the user can see the list of all apps that have been authorized:

Navigate to the Settings menu and select 'My Profile'.  You can manage applications in the bottom section called 'Authorized Apps'

Click Navigate here to see all authorized apps.

If user clicks Revoke Access - your application will no longer be able to get new tokens until access is approved again (as described in authentication section).

NOTE: tokens that were issued before user revoked access will remain valid until they expire (no longer than 1 hour).

Did this answer your question?