API

The Envoy API is a simple interface for retrieiving case data, timesheet information, users and clients from Envoy. It can also be used to update cases on Envoy.

Usage

You can see your usage of the API in Settings > API. At the moment there are no restrictions on API usage. However, we may add restrictions in future depending upon usage. We recommend using caching appropriately in your applications to minimise the risk that limits become necessary.

Testing

You can test your API integration against the demonstration account of Envoy. The demonstration account is at demo.envoyapp.com. There is an API key already set up for the Envoy demo: CB4BH8FF2ZH9BD333HTVDD85NYMCPMC1. Please note - the demo installation sends no emails and data is reset to a default state on the hour.

Sample Code

Sample code for PHP is available at GitHub.

Protocols and Authentication

We recommend you use SSL (HTTPS) to connect to the API, though it will also accept HTTP connections.

Authentication of all requests is done with an API key and a pair of HTTP headers - X_API_SIGNATURE and X_API_REQUEST_TIME. API keys can be generated in Settings > API (you can have as many as you want). You should never send your API key directly with a request.

  • X_API_REQUEST_TIMEThe X_API_REQUEST_TIME header is sent with every request to the API, and is the UNIX timestamp of the request. The request will be rejected if the X_API_REQUEST_TIME is not within the last 30 seconds.
  • X_API_SIGNATUREThe X_API_SIGNATURE header is an MD5 hash of an API key and the time you set in the X_API_REQUEST_TIME header (see the example code below). It should change with every request.

Example PHP Code:

$api_key = 'KSTHBX12ST5Z969LVN85Z8EPK0CXPNYC'; // Generate this in your Envoy account.
$url = 'http://account-alias.envoyapp.com/api/cases/'; // The API URL you want to interact with
$request_time = time(); // Time of request
$api_signature = md5($api_key . $request_time); // Generate signature

// Fetch URL with CURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X_API_SIGNATURE: ' . $api_signature, 'X_API_REQUEST_TIME: ' . $request_time));
curl_setopt($ch, CURLOPT_TIMEOUT, 5);  
curl_setopt($ch, CURLOPT_MAXREDIRS, 5);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
$file = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

Responses

All responses from the API are in JSON format. Each response contains a field called "result", which will contain either "error" or "success". If the "result" is "error", more information about the error will be contained in the "messages" array field. Every response also contains a "response_timestamp" field.

Fetching Views / Lists of Cases

You can fetch cases from the following type of API URL (where account-alias is replaced with your own account alias). This URL will only respond to GET requests.

http://account-alias.envoyapp.com/cases/options/

You can define the cases returned using similar URLs to those used on Envoy. Every case listing (view) includes at the top an "API URL", and this is the URL you use to retrieve that case listing from the API.

For example, if you want to use the API to list open cases owned by user 1, you would perform the following steps:

  • 1. Visit your Envoy installation and click "New View".
  • 2. Select your view options as usual (for example, Cases with a status of "Open" and Cases owned by user 1).
  • 3. Click "Go To New Listing".
  • 4. Find "API URL" at the top of the page. This is the URL you need to use to retrieve this case listing from the API.

Case view URLS are relatively simple, and you can construct your own once you have got to grips with the format.

The following variables can be passed in as normal querystring parameters:

  • page_numberThe page number (defaults to 1) (10 items per page).

The response is a JSON encoded array containing the following:

  • listing_descriptionA textual description of the list of cases being returned.
  • page_numberThe page number of this response.
  • total_casesThe total number of cases matching this query.
  • casesAn array of cases, with each item containing:
    • case_idThe ID of the case.
    • titleThe title of the case.
    • statusThe status of the case.
    • priorityThe priority of the case.
    • priority_nameThe label for the priority of the case.
    • estimateThe time estimated for the case.
    • owner_user_idThe current case owner ID.
    • client_idThe client ID.
    • openedThe unix timestamp when the case was opened.
    • dueThe unix timestamp when the case is due.
    • last_changeThe text of the last case update.
    • last_change_dateThe unix timestamp when the case was last updated.
    • last_change_user_idThe user ID of the last person to change the case (if change was not made by a user, this will be 0).
    • last_change_user_nameThe username of the last person to change the case.
    • last_change_user_emailThe email address of the last person to change the case, if the update was emailed to Envoy (an update made through the API will have an email address here of "api@example.com").
    • depends_onAn array of case IDs of the cases this case depends upon.
    • parent_caseThe parent case ID.

Fetching Individual Cases

You can fetch individual cases from the following type of API URL (where account-alias is replaced with your own account alias and 123 is replaced with the ID of the case you are collecting). This URL will only respond to GET requests.

http://account-alias.envoyapp.com/cases/123/

There are no options for this API call.

The response is a JSON encoded array containing the following:

  • case_idThe ID of the case collected.
  • total_timeThe total time logged to this case or its children, in seconds.
  • childrenAn array of the case IDs of any child cases.
  • updatesAn array of case updates, with each item containing:
    • update_user_idIf this case update was performed by a user, the user ID. (0 indicates this update was not performed by a normal user.)
    • update_email_addressIf this case update was performed by email or an automated process, this will contain the associated address.
    • update_dateA unix timestamp of the case update.
    • owner_user_idThe user ID of the case owner.
    • case_titleThe case title.
    • client_idThe case client id (0 indicates this case is not assigned to a client).
    • parent_case_idThe case ID of the parent case (0 indicates no parent case).
    • depends_onAn array of the IDs of any cases on which this case depends.
    • dueA unix timestamp of the due date of the case.
    • estimateThe number of hours it is estimated the case will take to complete.
    • priorityThe priority of the case.
    • priority_nameThe label for the priority of the case.
    • statusThe status of the case, one of "new", "active", "hold", "resolved" or "closed".
    • private_caseEither "true" or "false", indicating whether this case is private.
    • private_updateEither "true" or "false", indicating whether this case update is private.
    • update_messageThe case update message.
    • attachmentsAn array of any attached files.
    • tagsAn array of any case tags.

Adding and Updating Cases

You can send case updates and create new cases using the following API URLs (where account-alias is replaced with your own account alias). These URLs will only respond to POST requests.

http://account-alias.envoyapp.com/api/cases/add/

http://account-alias.envoyapp.com/api/cases/123/update/

The following variables can be passed in as normal POST parameters:

  • owner_user_idThe user ID of the case owner.
  • case_titleThe case title.
  • client_idThe client ID (0 indicates no client).
  • parent_case_idA parent case ID (0 indicates no parent).
  • depends_onA space-separated list of case IDs on which this case depends.
  • dueA unix timestamp of the due date of the case.
  • estimateThe number of hours it is estimated the case will take to complete.
  • priorityThe priority of the case.
  • statusThe case status, one of: "active", "hold", "resolved" or "closed".
  • private_case1 or 0 to indicate whether the case should be private.
  • private_update1 or 0 to indicate whether the case update should be private.
  • update_messageThe text of the update (can contain some HTML tags: <p> <br> <br/> <b> <i> <strong> <em> <ul> <ol> <li> <blockquote> <a>).
  • tagsA space-separated list of case tags.

When updating a case, if any of the above are omitted in the post, the case will keep the value already assigned.

The response is a JSON encoded array indicating whether the post was successful or not.

If adding a new case, the response will also include the ID of the newly created case.

Fetching Clients

You can fetch clients from the following type of API URL (where account-alias is replaced with your own account alias). This URL will only respond to GET requests.

http://account-alias.envoyapp.com/api/clients/

There are no options for this API call. The call returns all clients.

The response is a JSON encoded array containing the following:

  • total_clientsThe total number of clients.
  • clientsAn array of clients, with each item containing:
    • client_idThe ID of the client.
    • client_parent_idThe ID of the parent client (0 indicates no parent client)
    • client_nameThe name of the client.
    • client_aliasThe alias of the client (used for automatic categorisation of emails).
    • client_manager_user_idThe user ID of the client manager.
    • client_activeEither "true" or "false" to indicate whether the client is active.

Fetching Users

You can fetch users from the following type of API URL (where account-alias is replaced with your own account alias). This URL will only respond to GET requests.

http://account-alias.envoyapp.com/api/users/

There are no options for this API call. The call returns all users.

The response is a JSON encoded array containing the following:

  • total_usersThe total number of users.
  • usersAn array of users, with each item containing:
    • user_idThe ID of the user.
    • user_nameThe username of the user.
    • user_emailThe email address of the user.
    • user_timezoneThe timezone of the user.
    • user_accessOne of "Normal", "Manager", "Administrator" or "Client" indicating the level of access of this user.
    • user_last_loginA unix timestamp of the last time the user was seen by Envoy.
    • user_activeEither "true" or "false" to indicate whether the user is active.
    • client_idIf the user is a client user account, this will contain the client ID. A client ID of 0 indicates that this is an internal user.

Fetching Timesheets

You can fetch timesheets from the following type of API URL (where account-alias is replaced with your own account alias). This URL will only respond to GET requests.

http://account-alias.envoyapp.com/api/time/

Timesheets can be retrieved either for a user, a client or a case.

The following variables can be passed in as normal querystring parameters:

  • page_numberThe page number (defaults to 1).
  • items_per_pageThe number of timesheet entries per page (defaults to 25).
  • user_idThe number of timesheet entries per page (defaults to 25).
  • client_idThe number of timesheet entries per page (defaults to 25).
  • case_idThe number of timesheet entries per page (defaults to 25).
  • start_time_afterOnly return timesheet entries where the start time is after, or equal to, this UNIX timestamp.
  • start_time_beforeOnly return timesheet entries where the start time is before, or equal to, this UNIX timestamp.
  • end_time_afterOnly return timesheet entries where the end time is after, or equal to, this UNIX timestamp. If set to zero, this returns all current work.
  • end_time_beforeOnly return timesheet entries where the end time is before, or equal to, this UNIX timestamp. If set to zero, this returns all current work.

The response is a JSON encoded array containing the following:

  • total_entriesThe total number of timesheet entries.
  • page_numberThe page number of this response.
  • user_idThe ID of the user whose timesheet was requested.
  • client_idThe ID of the client whose timesheet was requested.
  • case_idThe ID of the case whose timesheet was requested.
  • entriesAn array of timesheet entries, with each item containing:
    • user_idThe ID of the user this entry was associated with.
    • client_idThe ID of the client associated with this entry (0 indicates this entry is not associated with a client).
    • case_idThe ID of the case this entry was associated with (0 indicates this entry is not associated with a case).
    • case_titleThe title of the associated case, if this entry is associated with a case.
    • start_timeThe UNIX timestamp of the time this entry began.
    • end_timeThe UNIX timestamp of the time this entry ended (0 indicates this work is currently going on).
    • entry_noteA note about this timesheet entry, if set.