REST API

The following describes how to initiate a connection to our REST API.

URL Endpoint

We enforce TLS encryption by requiring the use of HTTPS. The URL for the REST API endpoint is as follows:

https://api.teletracker.net

REST Operation Types

Since we implement the principles of REST in this API, you will be able to send us various different types of operations that correspond to POST, GET, PUT, and DELETE HTTP requests. In some operations where it is not very obvious what kind of operation is to be performed, we default to POST.

How to Format Your Request Body for POST, PUT, and PATCH Requests

When you make a POST, PUT or PATCH request to us, you will need to include a HTTP request body using a suppported encoding scheme. You must set the Content-Type and Content-Length headers on your HTTP request. This is standard functionality on any client library. We support three different encoding schemes for request data: application/x-www-form-urlencoded, multipart/form-data, and application/json.

How to Pass Data to Us for GET and DELETE Requests

The standard and easiest (and probably the best) way to do this, which is compatible with all web browsers, is to generate a query string with the key=value pairs in it. We also support passing a HTTP request body for these types of events as well. The same encoding schemes that are supported for POST requests are also supported here.

curl -u 'test@user.com:testpassword' \
'https://api.teletracker.net/reports/call-data?start_date=2022-10-01&end_date=2022-10-02&account_id=12345'

{"success": true, "data": [ ... ]}

HTTP Response Codes

Every API request will result in a HTTP response code and a HTTP response body of some kind. With one exception, that is. Read on. Here are some typical HTTP response codes you may receive:

Code	Status	Description
200	Success!	The operation was successful. Be sure to check the JSON response body for any relevant information.
400	Bad Request	This most likely means that you are missing some required variables for the request. If that is the case, refer to the JSON response body for what variables are missing. You might also receive this if some kind of generic problem with your input data has occured, but most likely, you will receive one of the following 400 series codes in that case.
401	Unauthorized	This means that you are not authenticated, or username and/or password is incorrect.
403	Forbidden	You may receive this response code if you do not have sufficient permissions to perform an operation. Note that you may also receive code 401.
404	Not Found	This means that some entity, object, or record that you have requested does not exist. Refer to the JSON response body for details.
409	Conflict	This means that you have passed us conflicting information in your request. We did not perform the operation in order to avoid potentially breaking something. You must resolve the conflict. Refer to the JSON response body for details.
415	Unsupported Media Type	You will receive this code if you did not properly pass your request data to us using a supported encoding scheme and method.
422	Unprocessable Entity	Lots of things can generate this response code. It means that all required variables were passed to us, but something about them is not right. Refer to the JSON response body, which will contain a description of what went wrong and how to fix it.
500	Internal Server Error	Something went wrong on our side. You may or may not get a JSON response body here, and the operation most likely did not complete or did not complete properly.

Format of Response Data

Except when streaming data, the REST API always sends response body to you in JSON format. The one exception is when you receive a response code that is in the 500 series: You may not get a response body in that case, so don’t rely on it to come back to you when checking for errors. When you do receive a response body in JSON format, there will always be a few standard variables that you can expect to exist.

Each JSON response will contain, at minimum, the following two variables. The success variable will always be either true or false, which represents the state of the requested operation. A success=true variable will correspond to a HTTP 200 code.

{
   "success": true,
   "guid": "84e2b789-d5f4-4634-98fe-dacc9fe42ba3"
}

Debugging API Responses

If you receive a 400 series HTTP code, you will usually also have additional information about the request in the JSON body, which may include a message that describes how to resolve the problem.

The following is an example of an attempt to initiate the RapidResponse system. That particular API call requires a few variables to be passed in order to work. In this hypothetical situation, no variables were passed in, which resulted in an error with a HTTP response code of 400. You can see that the error message tells you that they were not passed in, and what you need to do to fix it.

curl -X POST -u 'test@user.com:testpassword' \
'https://api.teletracker.net/voice/rapidresponse'

{
  "missingInputVars": [
    "account_id",
    "callee",
    "whisper_text"
  ],
  "guid": "23e53ccf-4c09-4785-928f-cdfc70befc35",
  "success": false,
  "errorCode": "MISSING_REQUIRED_PARAMS",
  "errorDetail": "One or more required input paramaters were missing"
}

If you need help with an API request, make sure you send our support team the guid value of the request. We’ll be able to look it up using internal debug tools. However, don’t wait too long. We only keep this kind of debug data for about two weeks.