API Integration Example: Locations

    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

    GEThttp://sb2.servicechannel.com/api2/odata/locations/Service.NearBy(latitude=0,longitude=0)  HTTP/1.1
    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:

    LocationResponseHeaders.jpg

    LocationResponse.jpg

    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:

    LocationResponse_selected.jpg

    If something wrong you will receive the response like this:

    LocationResponseHeaders_error.jpg

    LocationResponse_error.jpg

    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/ .