Requests

2 minute read

The ServiceChannel API uses the most common HTTP verbs to indicate actions against a collection or its elements and has resource-oriented request URLs. For the maximum number of requests you can send per minute, see Throttling.

HTTP Verbs

Use the following HTTP verbs for calling our API:

POST to create a resource.

GET to retrieve a resource or a list of resources.

PUT to update a resource.

DELETE to erase a resource.

Request URL

In the ServiceChannel API, each resource or collection of resources is identified by a unique URL, such as:

https://sb2api.servicechannel.com/v3/workorders/{workorderId}

Usually, our request URLs consist of the following elements:

Request URL structure

  • Protocol identifier. Make all API requests over HTTPS. Calls over plain HTTP result in 400 Bad Request responses.
  • Environment prefix. sb2 is an environment prefix and must be present when you make calls in the Sandbox2 Environment. Omit the prefix when you work in the Production Environment.
  • Base URL. The base URL is api.servicechannel.com.
  • Version prefix. v3 is the API version specifier. When you omit the version prefix, the call points to the minimum supported version of the API. As for now it is v3, but in the future the next release will be v4. We recommend to always specify the API version to avoid possible errors.
  • URI for the command. URI contains the resource names and unique resource IDs. Before making a call, substitute a valid ID value for placeholders that are marked with curly brackets, for example, {workorderId}. When the request URL contains odata, you can use the OData system query options when calling this endpoint.

For API v3 and SB2 Environment, a sample request to get information on the word order #12345678 might look like:

GET https://sb2api.servicechannel.com/v3/workorders/12345678 HTTP/1.1
Authorization: Bearer {access_token}

Headers

HTTP headers are an important part of our API. They set or represent important request and response metadata.

There is one request header that is always required. This is the Authorization header that should contain your access_token. See Authentication for more details.

We also recommend to include the Content-Type header set to application/json in all POST and PUT requests when you pass data in JSON format.

Parameters

Many API methods take one or more parameters, either required or optional. These parameters could be of different types — for example, a query, path, or body.

Always check the API Reference to find out which parameters can be included when making calls to a particular resource.

Duplicate Request Prevention

To prevent duplicate POST and PUT requests, there is a 10-second duplicate request timeout.

Sometimes, due to network issues, you may receive an error even though your request actually worked out. If you send a second identical request within 10 seconds after the first successful request, we will reject the second request with a 406 Duplicate Request response code and the following response body:

{
   "Reason": "Duplicate request/request already processed",
   "ProcessedRequestInfo": "…"
}

That is how you know that the first request was successful. Retrieve the response to the first request in the ProcessedRequestInfo attribute.