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 that 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 you to always specify the API version to avoid possible errors.
  • URI for the command. The URI contains resource names and unique resource IDs. Before making a call, replace placeholders that are marked with curly brackets — for example, {workorderId} — with a valid ID value. When the request URL contains odata, you can use the OData system query options when calling this endpoint.

For API v3 and Sandbox2 environment, a sample request to get information on the work order #12345678 might look like this:

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.

In our API, there is only one request header that is always required. For each request, add the Authorization header, and include your access_token in it. See Authentication for more details.

We also recommend including 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 can be of different types — for example, a query, path, or body.

Always check the API Reference to find out what parameters to include 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 406 Duplicate Request response code and the following response body:

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

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

Updated: