project management on time
5pm API developer's guide describes how to use 5pm API to access and manage you 5pm account data. This guide is intended for developers who want to programmatically access their 5pm account data through their own applications.
Using 5pm API, you can access and manage groups, projects, tasks, activity and users in 5pm.
To access and manage your 5pm account using 5pm API you must build your client application that connects to one or more of the provided web services.
The core messaging technology of 5pm API is SOAP (Simple Object Access Protocol).
The 5pm API is composed of the following web services:
In order to use 5pm API you must be a registered 5pm user.
Attention! Be careful with the API – you can lose your data.
In order to start using 5pm API, you need:
service host: your account host name (ex: demo.5pmweb.com)
login: your login email
password: your password
The operations provided by the web service are defined in WSDL files. Before connecting to a web service, you need to know the URL that points to its WSDL file. Each 5pm API web service has its own WSDL. The URL for each WSDL has the following form, where <version> is the service version and <service host> is your customer account host:
example: https://demo.5pmweb.com/api/v2/wsdl/authentication.wsdl
The details of how your client application connects to the WSDL depends on the programming language and SOAP toolkit being used. SOAP toolkits typically provide a function for connecting to a service at a specified URL. For example, the following PHP code connects to API version 2:
Uppercase types, such as Project and Task, shown throughout this guide's API Reference are complex data structures or enumerations defined in the XSD:
Data Types: https://<service host>/api/<version>/wsdl/schema.xsd
Firstly, you must provide client authentication using AuthenticationService. After you get the sessionId (using operation signIn) you must send it with each request via Soap Header. If you don't do that — you will get an exception with authentication error message (you can send the authentication request without sessionId header).
Current version is v2.
The Shut Down of old versions will be announced via 5pm blog.
The 5pm API Web Services uses rpc-style versions of the simple object access protocol (SOAP). A client program sends a SOAP request; the web service processes the request and sends a response. Both the request and the response are packaged as XML messages that have a header and a body. The header contains metadata about the message, and the body specifies the requested operation.
The requests that a web service can process are defined in a web services definition language (WSDL) file in XML. The WSDL file describes the operations that the web service can perform, the required parameters for each operation, and the response for each operation.
5pm also supports GET and POST bindings, that are described in the same WSDL files.
Example:
https://demo.5pmweb.com/api/v2/service/get/authentication/signIn?login=<login>&password=<password>
https://demo.5pmweb.com/api/v2/service/get/projects/getAll?sessionId=<sessionId>
https://demo.5pmweb.com/api/v2/service/get/projects/getAll?_login=<login>&_password=<password>
/**
* 5pm api v2 example: create/read/update/remove projects
*/
define('API_HOST', 'demo.5pmweb.com');
define('API_USERNAME', 'blumbergh@initechweb.com');
define('API_PASSWORD', '1111');
require('lib/FivePm/Api.php');
try {
$api = new FivePm\Api(API_HOST);
if($api->getError() != null) {
throw new Exception($api->getError());
}
// try to sign in
if (!$api->signIn(API_USERNAME, API_PASSWORD)) {
throw new Exception("Authorization failed");
}
// create a new project
$project = $api->projects->add(
array(
'name' => "New Api project"
)
);
// update the project
$project->name = $project->name . " (upd)";
$projectUpdateResult = $api->projects->update($project);
// create another project
$anotherProject = $api->projects->add(
array(
'name' => "Another Api project",
)
);
// add a task to the project
$task = $api->tasks->add(
array(
'name' => 'New api task',
'projectId' => $project->id,
)
);
// update the task
$task->name = $task->name . ' (upd)';
$taskUpdateResult = $api->tasks->update($task);
// add another task
$anotherTask = $api->tasks->add(
array(
'name' => 'Another api task',
'projectId' => $project->id,
)
);
// add a sub-task to previously created task
$subTask = $api->tasks->add(
array(
'name' => 'New api sub-task',
'parentId' => $task->id,
)
);
// move the task to another project
$task->projectId = $anotherProject->id;
$api->tasks->update($task);
// move another task to another project
$anotherTask->projectId = $anotherProject->id;
$api->tasks->update($anotherTask);
// move $task as a sub-task of "$anotherTask"
$task->parentId = $anotherTask->id;
$api->tasks->update($task);
// get 10 tasks from project
$tasksList = $api->tasks->getList(
array('projectId' => $project->id), // - filter
0, // - offset (by default '0')
10, // - count (by default '20')
true // - load task team true/false (by default 'false')
);
// add a new message to the created project
$msg = $api->activity->add(
array(
'type' => 'msg',
'projectId' => $project->id,
'text' => 'A message on api project',
)
);
// add a new message to the created task
$msgOnTask = $api->activity->add(
array(
'type' => 'msg',
'taskId' => $task->id,
'text' => 'A message on api task',
)
);
// add a new progress to the created task
$progressOnTask = $api->activity->add(
array(
'type' => 'progress',
'taskId' => $task->id,
'progress' => 34,
'text' => 'A progress note on api task',
)
);
// add a new progress to the sub-task
$progressOnSubTask = $api->activity->add(
array(
'type' => 'progress',
'taskId' => $subTask->id,
'progress' => 77,
'text' => 'A progress note on api task',
)
);
// get 10 messages from task
$msgList = $api->activity->getList(
array('taskId' => $task->id), // - filter
0, // - offset (by default '0')
10, // - count (by default '20')
true, // - load files (by default 'false')
true // - load project/task name (by default 'false')
);
// remove the progress from the sub-task
$api->activity->remove($progressOnSubTask->id);
// remove the task
$api->tasks->remove($task->id);
// remove the project
$api->projects->remove($project->id);
// remove another project
$api->projects->remove($anotherProject->id);
// sign out
$api->signOut();
echo "The planet is safe now!\n";
} catch (Exception $exc) {
echo "Something went wrong: " . $exc->getMessage() . "\n";
}
Our partners at orange5 can help you with that. They provide custom web/mobile/desktop development services at a good speed and reasonable price. The orange5 team built with our API integrations with Outlook, Gmail, Alexa, as well as iOS and Android apps. www.orange5.com
Last updated: November 8, 2019
