Requests
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:
- 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 isv3
, but in the future, the next release will bev4
. 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 containsodata
, 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.