| API Overview |
| Example |
Customers  |
| Companies |
| Technicians |
| Technician Groups |
| Tickets |
| Ticket History |
| Ticket Attachments |
| Billing Line Items |
| Billing Invoices |
| Time Tracking |
| Knowledge Base Articles |
| Scheduling |
| Asset Managements |
| ReadyDesk API Reference |
| This document discusses the ReadyDesk Web Services API, a collection of HTTP interfaces to ReadyDesk providing methods for adding, updating and retreiving data within the ReadyDesk database.
The links on the left of this page provide detailed usage, including input and output variables, as well as descriptions for each variable and example usage and responses. |
| Getting Started |
| First, you will need an API key. To get your API key log into your ReadyDesk admin console and go to WEB SERVICES API > SETTINGS in the left tree menu. Next to the field "API Key" you will see a button labeled "Generate". Click that button and confirm the prompt and a new API key will be generated for you (Please note that the API key will not be saved until you click the submit button). Be sure to keep your API key private to prevent unauthorized access. If you need to change your API key in the future you will need to be sure to update any applications you have that are using the ReadyDesk web services API with the new key.
You will also notice on that page that you can limit access to the API by IP addresses. This is a security feature to prevent unauthorized users from accessing your API. When enabled, only the IP addresses listed in the "Allowed IPs" will have access to the API. Any attempts to access the API from an IP address that is not listed there will result in an error message. All web service requests will go to the same base URL, similar to the following: http://localhost/readydesk/API/?key=your key here&action= Your actual URL will vary depending on the directory name where ReadyDesk is installed and where on your network you are accessing the web service from. The "variables" used with the web service API are the parameters supplied in the URL after the question mark (?), separated by ampersands (&) and the values of these variables are separated by an equal sign (=). For example, in the above URL you have the variables "key" and "action" (?key=your key here&action=). The "action" variable will be the name of the method you would like to send the request to. The available action values are listed on the left side of this page. Each "action" method requires its own set of variables to perform a request, which again are detailed on the pages using the links on the left side of this page. |
| The output variable |
|
When a successful request is made to the Web Services API, the response can be received in 3 different formats. The formats are XML, JSON and URL delimited. The default format is XML. If the output variable is not supplied in the request the response will be returned in XML.
Example Usage: http://localhost/readydesk/API/?key=your key here&action=get_tickets&tid=*&output=xml The "URL delimited" format is named such because it is similar to a URL, in that the output variables and values are separated by ampersands (&) and equal signs (=). For example, a request sent to the action "get_tickets" would return a response similar to the following: tid=34&cid=demo&company_id=1&company_name=Demo+Company&contact=John+Smith&phone=404-000-0000&email=John.Smith%40company.com If more than one record is returned in URL delimited format they will be separated by a new line (commonly referred to as "\r\n" in Javascript, PHP and C# and vbCrLf in VB.Net). You can use the new line as a delimiter to split the separate records into an array. |
| Wildcards |
| Many of the methods that are used for retrieving information from ReadyDesk, such as "get_tickets" will allow for wildcard values. The wildcard value will always be *. For example, if you wanted to retrieve all tickets, you would use "&tid=*", as shown in the URL above. |
| Limiting Results |
| You may not always want to request all records at once, especially if you have a large amount of data in your database. To get fewer results and to speed up the response time, many of the methods allow for the "count" variable. This allows you to specify how many records to return. For example, if you only want to get the first 50 records you would include &count=50 in the URL. If you just need a count of the records, include &count_only=Y. This variable comes in handy when paging records, as discussed in the next section. Some of the action methods also allow you to limit alphabetically. For example, "get_customers" has the "start_cid" and "end_cid" variables. This allows you to specify one or more letters to start and end the responses at. For example, if you only wanted to retrieve customer records that start with the letter S, you would inlcude &start_cid=S&end_cid=S in the URL. |
| Paging Results |
|
You can easily get "pages" of data for any of the "get_" actions. Just include the "count" and "page" variables. For example, to get the first 10 records from the "get_customers" action you would use the following URL:
http://localhost/readydesk/API/?key=your key here&action=get_customers&cid=*&count=10&page=1 To determine the number of pages that will be returned, simply request the count first using the "count_only", then divide the returned count by the number of records you want for each page. Example: http://localhost/readydesk/API/?key=your key here&action=get_customers&cid=*&count_only=Y Response: <?xml version="1.0" ?> <response> <count>65</count> </response>Now divide the total by the desired page size. In this case, we want 10 records per page: 65 / 10 = 6.5 Whenever a decimal value is returned you will always round that number up to the next whole number. Rounding 6.5 up to the next whole number tells you that there are 7 available pages of records. Please note that paging of records will only work when the * wildcard character is used. The variables that allow for the wildcard character are documented for each action. |
| URL Encoding |
|
Because some of the response values can contain ampersands (&) and other characters that could cause errors when parsing them, some of the values are returned as URL encoded strings. For example, when using the "get_history" action, the value for the variable "history_text" could have ampersands in it, which would cause issues when using XML or URL delimited output formats. URL encoding the value will safely allow the value to be retrieved without breaking the formatting. After retrieving the value you would then URL decode it in whatever programming language you are using. For example, in PHP you would use urldecode() and in C# and VB.Net you could use HttpUtility.UrlDecode() or HttpContext.Current.Server.UrlDecode().
Only the output values that are URL encoded will need to be decoded. The output variables that are returned as URL encoded strings are documented for each action. |