Access token request
First you should authenticate against ServiceChannel and receive authorization code back. To request an authorization code, the following request should be issued:
POST https://sb2login.servicechannel.com/oauth/token HTTP/1.1
Authorization: Basic ________
Content-Type: application/x-www-form-urlencoded
Host: sb2login.servicechannel.com
username=USERNAME&password=PASSWORD&grant_type=password
Authentication here should happen using client_id and client_secret as username (resource owner username) and password (resource owner user password). To prepare “Authorization: Basic” key you need encode client_id:client_secret to Base64 format. For it you can use the https://www.base64encode.org/.
You can find detailed description about Authentication and Authorization in our documentation: https://servicechannel.zendesk.com/hc/en-us/articles/208654056.
Call request to get Locations
After you have received an access token you can use it to access the resource by supplying it in the Bearer authorization header. There are two methods to get Locations: “GET /locations” and “GET /locations/Service.NearBy(latitude={latitude},longitude={longitude})”.
Here is an example to retrieve Locations using ServiceChannel API V3 (OData):
GET http://sb2.servicechannel.com/api2/odata/locations HTTP/1.1
User-Agent: Fiddler
Authorization: Bearer __________
Host: sb2.servicechannel.com
User-Agent: Fiddler
Authorization: Bearer __________
Host: sb2.servicechannel.com
The Open Data Protocol (OData) is a data access protocol built on core protocols like HTTP and commonly accepted methodologies like REST for the web. More detail description about it you can found in http://www.odata.org.
Model Schema and parameters are presented in https://sb2api.servicechannel.com/swagger/ui/index#!/Locations/Locations.
Examples to get Location using different query options
The $select System Query Option
Specifies a subset of properties to return and the order in which the columns of data will be organized.
Returns only “Id” list of the locations.
The $filter System Query Option
Specifies an expression or function that must evaluate to true for a record to be returned:
The request to get Locations by SubscriberId:
Logical operator “eq” (Equal) mean that the method will return all Locations with SubscriberId equal 2000001305. Symbol “%20” is space symbol.
The request to get Locations by Name start with ‘S’ symbol:
The request to get Locations by range:
Returns locations where Latitude>10 and Longitude<-107. The query uses operators:
-
gt: Greater than;
-
lt: Less than;
-
and: Logical and.
The $orderby System Query Option
Determines what values are used to order a collection of records. By default, the order is ascending.
Return Location name list ordered by Location name.
The $top System Query Option
Determines a maximum number of records to return.
Return one location.
The $skip System Query Option
Sets the number of records to skip before retrieving records in a collection.
Return location list since the eleventh item.
Find detailed description of OData system query options using the OData endpoint at https://msdn.microsoft.com/en-us/library/gg309461(v=crm.7).aspx#BKMK_expand
Response Examples
The typical response when the calls done is:
Http Status Code 200 (OK) indicates that the request succeeded and that the requested information is in the response.
While using $select option you will receive the requested information only for selected item. For example https://sb2api.servicechannel.com/odata/locations?%24select=Id:
If something wrong you will receive the response like this:
Http Status Code 401 (Unauthorized) indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.
Find detailed information about HTTP Status Codes at https://httpstatuses.com/ .