menu
How to use smartQ

API

About this Guide

smartQ API developer's guide describes how to use SmartQ API to access and manage you smartQ account data. This guide is intended for developers who want to programmatically access their smartQ account data through their own applications.

smartQ API represents a REST set of resources which can be accessed/managed using GET/POST/PUT/DELETE http methods. As a response to an api request, the server returns a JSON encoded array.

For example:

									 	
{"error":{"type":null,"code":405,"message":"method \"GET\" not found for resource \"\""},"data":null}
									 	
									 

"error" field - contains error details or is null if no error occurred.
"data" field - contains method call response or is null if an error occurred.

The root resource is located at http://.smartqweb.com/api/v1. Not every resource supports every method. If a resource does not support a method - exception is thrown.

Signing Up for using smartQ API

In order to start using smartQ API, you need:

  • resource host: - your account host name (ex: demo.smartQweb.com)
  • login: - a valid user email
  • password: - a valid password for the provided login.
  • API access key – a client identifier, that can be obtained through “Options” > “API” on the top of your smartQ web interface (accessible to Administrators only).
  • Note: In case an API key is being regenerated – access to API is disabled for all software, that uses the old API access key.
  • Make sure you are using the current API key before performing any API requests.

Attention! Be careful with the API – you can lose your data.

Authentication and access

Every API resource requires user authorization. The authorization info should be provided using basic HTTPauthorisation header. Besides authorisation info, in order to access API resources, the client should provide an API access key. It should be sent using X-Auth-Client-Id HTTP header or X_AUTH_CLIENT_ID request parameter. If invalid API access key is provided - an error is returned:

										
{"error":{"type":null,"code":401,"message":"Authorization failed, invalid client id"},"data":null}
										
									

Available resources and methods

Users
  • GET /api/v1/users/me - returns authorised user's details
  • PUT /api/v1/users/me - updates authorised user's details
  • GET /api/v1/users - returns the list of users
  • POST /api/v1/users – adds a new user
    To POST/PUT user – please send properties as an array named "user":
    user[name] (string) = user name (required)
    user[email] (string) = user email (required, unique)
    user[password] (string) = user password (required)
    user[is_account_administrator] (bool) = true if user is an account administrator
    user[can_manage_projects] (bool) = true if user can manage (add) projects
    user[can_view_profiles] (bool) = true if user can view other users' profiles
    user[can_manage_profiles] (bool) = true if user can manage other users' profiles
    user[company] (string) = company name
    user[title] (string) = job title
    user[address] (string) = address
    user[work_phone] (string) = work phone
    user[cell_phone] (string) = cell phone
    user[comments] (string) = comments
  • GET /api/v1/users/<user id> - returns user details
  • PUT /api/v1/users/<user id> - updates user details
  • DELETE /api/v1/users/<user id> - deletes user
Projects
  • GET /api/v1/projects - returns the list of projects (accessible by user)
  • POST /api/v1/projects – adds a new project
    To POST/PUT project - new project properties should be sent as an array named "project":
    project[name] (string) = Project name text (required)
    project[description] (string) = project description text (optional)
  • GET /api/v1/projects/<project id> - returns project details
  • PUT /api/v1/projects/<project id> - updates project details
  • DELETE /api/v1/projects/<project id> - deletes project
Project Roles
  • GET /api/v1/projects/<project id>/roles - returns the list of project roles
  • POST /api/v1/projects/<project id>/roles – adds a new project role
    To POST/PUT role - send properties as an array named "role":
    role[name] (string) = role name (required)
    role[access_level] (int) = access level integer [0-5] (required)
    role[max_step] (int) = role max step id user can move tickets to (optional)
    role[can_edit_project] (bool) = true if users from this role can edit project settings
    role[can_manage_people_notes] (bool) = true if users from this role can edit other people notes
    role[can_see_private_notes] (bool) = true if users from this role can see private notes
  • GET /api/v1/projects/<project id>/roles/<role id> - returns project role details
  • GET /api/v1/projects/<project id>/roles/default - returns default role details
  • PUT /api/v1/projects/<project id>/roles/<role id> - updates project role details
  • PUT /api/v1/project/<project id>/roles/default - updates default project role details
  • DELETE /api/v1/projects/<project id>roles/<role id> - deletes project role
Project Steps
  • GET /api/v1/projects/<project id>/steps - returns the list of project steps
  • POST /api/v1/projects/<project id>/steps - adds a new project step
    To POST/PUT step - send properties as an array named "step":
    step[name] (string) = step name (required)
    step[description] (string) = step description (optional)
    step[limit] (int) = step tickets limit (optional)
    step[pos] (int) = step position (optional)
  • GET /api/v1/projects/<project id>/steps/<step id> - returns project step details
  • PUT /api/v1/projects/<project id>/steps/<step id> - updates project step details
  • DELETE /api/v1/projects/<project id>/steps/<step id> - deletes project step
Project Custom Fields
  • GET /api/v1/projects/<project id>/custom_fields - returns the list of project custom fields with available values (for choice type fields only)
  • GET /api/v1/projects/<project id>/custom_fields/<field name> - returns field properties including the available values (where applicable)
  • POST /api/v1/projects/<project id>/custom_fields - adds a new custom filed to the project
    To POST/PUT a custom field - send properties as an array named "field":
    field[type] (string) = field type (required); available values: float, string, text, choice
    field[label] (string) = field label (required)
    field[hint] (string) = field description
    field[required] (bool) = field is mandatory or optional
    field[pos_type] (string) = defines the way the new custom field is represented in smartq web interface; available values: single, double
    field[options][choiceType] (string) = type of choice field; available values: checkbox, radio, select
    field[options][min] (float) = minimal allowed value (for float type fields only)
    field[options][max] (float) = maximal allowed value (for float type fields only)
    field[options][fieldLayout] (string) = layout of options in smartq web interface (for radio and checkbox choiceTypes only)
  • PUT /api/v1/projects/<project id>/custom_fields/<field name> - updates custom filed details
  • DELETE /api/v1/projects/<project id>/custom_fields/<field name> - deletes custom field
Project Custom Field Values (for custom fields of type "choice")
  • GET /api/v1/projects/<project id>/custom_fields/<field name>/values - returns the list of custom field values
  • GET /api/v1/projects/<project id>/custom_fields/<field name>/values/<value id> - returns field value properties
  • POST /api/v1/projects/<project id>/custom_fields/<field name>/values - adds a new value to the custom field
    To POST/PUT a field value - send properties as an array named "value":
    value[title] (string) = value title (required);
    value[is_default] (bool) = value is default for this custom field
    value[pos] (bool) = value position in the list
  • PUT /api/v1/projects/<project id>/custom_fields/<field name>/values/<value id> - updates custom filed value details
  • DELETE /api/v1/projects/<project id>/custom_fields/<field name>/values/<value id> - deletes custom field value
Tickets
  • GET /api/v1/projects/<project id>/tickets – returns the list of tickets
    custom_fields (bool) = 1 or 0 to include custom field values for each ticket (might increase the response time)
    assigned_to (bool) = 1 or 0 to include info on assigned users for each ticket (might increase the response time)
  • POST /api/v1/projects/<project id>/tickets – adds a new ticket
    To POST/PUT ticket - send properties as an array named "ticket":
    ticket[name] (string) = ticket name text (required)
    ticket[description] (string) = ticket description text (optional)
    ticket[step_id] (int) = ticket step_id (required)
    ticket[tags] (string) = comma separated tags (optional)
    ticket[required_by] (string) = required by date (optional)
    ticket[assigned_to] (int[]) = array of user id's to assign ticket to (optional)
    ticket[notify_involved] (bool) = 1 or 0 to send notification to ticket team
  • GET /api/v1/projects/<project id>/tickets/<ticket id> - returns ticket details
  • PUT /api/v1/projects/<project id>/tickets/<ticket id> - updates ticket details
  • DELETE /api/v1/projects/<project id>/tickets/<ticket id> - deletes ticket
Notes
  • GET /api/v1/projects/<project id>/tickets/<ticket id>/notes – returns the list of notes
  • POST /api/v1/projects/<project id>/tickets/<ticket id>/notes – adds a new ticket note
    To POST/PUT note - send properties as an array named "note":
    note[text] (string) = note text, with some html tags allowed (required)
    note[private] (bool) = private flag (optional)
    note[notify_users] (bool) = true to notify uses about new message (optional)
    note[users] (array) = array of user ids to notify note[has_attachments] (bool) = if true than no notifications are sent until "is_last_file" flag is received together with one of the later uploaded files
  • GET /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id> - gets note details
  • PUT /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id> - updates note details
  • DELETE /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id> - deletes note
Files
  • GET /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id>/files - returns list of files attached to note
  • POST /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id>/filesv2 - upload new file
    To POST file - send file as a standard POST file named "file" (please check the example). Please note that you have to make a separate request for each file you would like to upload.
  • GET /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id>/files/<file id> - returns file details
  • GET /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id>/files/<file id>/download - returns file body
  • DELETE /api/v1/projects/<project id>/tickets/<ticket id>/notes/<note id>/files/<file id> - deletes file
Nota bene
  • To change the default number of returned items in a list - add count parameter to the query.
  • To get the list of items starting not from the first item, but from other one - add offset parameter to the query.

The points mentioned above are applicable to all the resources returning lists of items.
For example, to get 10 projects starting from 20th project - use the following url:
http://domain.smartqweb.com/api/v1/projects?count=10&offset=20

Examples

Get projects list
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));
$projects = curl_exec($curl);
               		
								
Get project custom fields list
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects/99999/custom_fields");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));
$fields = curl_exec($curl);
               		
               	
Add project
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_POST, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));

$post = array(
   'project' => array(
       'name' =>'New Project',
       'description' => 'New Project Description'
   )
);
curl_setopt ($curl, CURLOPT_POST, true);
curl_setopt ($curl, CURLOPT_POSTFIELDS, http_build_query($post));

$project = curl_exec($curl);
               		
               	
Remove project
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects/99999");
curl_setopt ($curl, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));

$result = curl_exec($curl);
               		
               	
Add ticket
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects/99999/tickets");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_POST, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));

$post = array(
   'ticket' => array(
       'name' =>'New Ticket',
       'description' => 'New Ticket Description',
       'step_id' => 88888,
       'assigned_to' => array(1, 2, 3, 5)
   )
);
curl_setopt ($curl, CURLOPT_POSTFIELDS, http_build_query($post));
$result = curl_exec($curl);
               		
               	
Add ticket with custom fields
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects/99999/tickets");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_POST, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));

$post = array(
   'ticket' => array(
       'name' =>'New Ticket',
       'description' => 'New Ticket Description',
       'step_id' => 88888,
       'assigned_to' => array(1, 2, 3, 5),
   // here come the values for the custom fields
       'f3' => 'some important info',
       'f4' => 2013,
       'f5' => array(1234, 4321)
   )
);
curl_setopt ($curl, CURLOPT_POSTFIELDS, http_build_query($post));
$result = curl_exec($curl);
               		
               	
Add note to ticket
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects/99999/tickets/77777/notes");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_POST, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));

$post = array(
   'note' => array(
       'name' =>'New Note'
    )
);
curl_setopt ($curl, CURLOPT_POSTFIELDS, http_build_query($post));

$result = curl_exec($curl);
               		
               	
Upload file
               		
$curl = curl_init();
curl_setopt ($curl, CURLOPT_URL, "http://domain.smartqweb.com/api/v1/projects/99999/tickets/77777/notes/55555/filesv2");
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($curl, CURLOPT_POST, true);
curl_setopt ($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC ) ;
curl_setopt ($curl, CURLOPT_USERPWD, "email@domain.com:11111");
curl_setopt ($curl, CURLOPT_HTTPHEADER, array(
   'X-Auth-Client-Id: 69a4d22883c57c436c4431c3982eecb2'));

$file_name = 'image.jpg';
$file_name_with_full_path = realpath($file_name);

//Notice the @ prefixing local file path - it does the trick.
$post = array(
    "file"=>'@'.$file_name_with_full_path,
);
curl_setopt ($curl, CURLOPT_POSTFIELDS, http_build_query($post));
$result = curl_exec($curl);