API

API

We now have a fully functioning API so you can integrate Copper with your other favourite cloud-based apps. If you would like to become a partner or require assistance, get in touch

Login

Request

Method URL
POST index.php?module=api&v=1&action=login

The parameters module , action and v can be passed using GET or POST.

v defines the api version to use. If v is not set, api version 1 will be used.

Type Param Value
POSTPOST usernamepassword stringstring

username

username reflects the username to use upon login.

password

password is the users password in clear text (as of API version 1). The API should only be used over HTTPS (SSL).

 

Response

Status Description
200 Sent, when Login was successful.{“response_code”:200,”message”:”Successful”,

“data”:

{

“logged_in”:true,

“api_version”:1,

“session_id”:”3EC9169EAECB3B39AB0CD8459956CD44″,

“user”:

{

“ID”:”1″,

“Username”:”admin”

}

}

}

data.session_id: the returned string must be provided with all requests to the api, that need authentication.
400 Sent, when username is missing.{“response_code”:400,”message”:”Bad Request”,

“data”:

{

“api_version”:1

}

}
401 Sent, when username and/or password do not match.{“response_code”:401,”message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

Request

Method URL           
POST index.php?module=api&v=1&action=login

The parameters  module ,  action  and  v  can be passed using GET or POST.

v  defines the api version to use. If v is not set, api version 1 will be used.

Type Param Value
POST

POST

 username

password

 string

string

username

username  reflects the username to use upon login.

password

password  is the users password in clear text (as of API version 1). The API should only be used over HTTPS (SSL).

 

Response

Status Description
200 Sent, when Login was successful.

{

“response_code”:200,

“message”:”Successful”,

“data”:

{

“logged_in”:true,

“api_version”:1,

“session_id”:”3EC9169EAECB3B39AB0CD8459956CD44″,

“user”:

{

“ID”:”1″,

“Username”:”admin”

}

}

}

data.session_id: the returned string must be provided with all requests to the api, that need authentication.
400 Sent, when username is missing.

{

“response_code”:400,

“message”:”Bad Request”,

“data”:

{

“api_version”:1

}

}
401 Sent, when username and/or password do not match.

{

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

 

Check Session

Check, if the provided session_id is valid.

Request

Method URL           
POST index.php?module=api&v=1&action=check_session

 

Type Param Value
POST session_id string

session_id

The  session_id  that was given in response to Login

Response

Status Response
200 In case of a valid session_id, Response will be an object similar to:

{

“response_code”:200

“message”:”Successful”

“data”:

{

“api_version”:1

“logged_in”:true

“session_id”:”3EC9169EAEDA3B39AB0CD8459956CD44″

“user”:

{

“ID”:”1″

“Username”:”admin”

}

}

}

In case of an invalid session_id, Response will be an object similar to:

{

“response_code”:200,

“message”:”Successful”,

“data”:

{

“logged_in”:false,

“api_version”:1

}

}

 

Logout

Logout the currently logged in user by invalidating the provided session_id.

Request

Method URL           
POST index.php?module=api&v=1&action=logout

 

Type Param Value
POST session_id string

 

session_id

The  session_id  that was given in response to Login

Response

Status Response
200 {

“response_code”:200,

“message”:”Successful”,

“data”:

{

“logged_in”:false,

“api_version”:1

}

}

 

Create Organisation

The Organisation  Manager will be set to the currently logged in User.

Request

Method URL           
GET index.php?module=api&v=1&action=create_organisation

 

Required Parameters:

Type Param Value
POST

POST

 session_id

data

 string

string (json object)

data

The  data  Parameter is the JavaScript representation of the new organisation.

For example: { Colour: “#aabbcc”, Name: “My new Organisation” }

Required data Attributes:

data attribute Value
Name string

Optional data Attributes:

data attribute Value
Colour

Phone1

IM1

IM2

FAX

Address1

Address2

City

State

Country

Postcode

URL

ContactEmail

 string (hex color code, #rrggbb)

string

string (Skype)

string (Twitter)

string

string

string

string

string

string

string

string (Website)

string (Email Address)

 

Colour

The Organisation  Colour  in form of a hexadecimal color code. If not set, the default colour of #82CE4C will be used.

 

Response

Status Response
200 {

“response_code”:200,

“message”:”The organization has been created.”,

“data”:

{

“api_version”:1,

“success”:true,

“ID”:”24″

}

}

data.ID: the ID of the newly created Organisation
400 {

“response_code”:400,

“message”:”Colour must be a valid hex color code. (like #FFFF00).”,

“data”:

{

“api_version”:1

}

}

Read Organisation

Get all Details of an organisation corresponding to an organisation id.

Request

Method URL           
GET index.php?module=api&v=1&action=read_organisation

 

Required Parameters:

Type Param Value
POST

POST

 session_id

id

 string

number

id

The  id  of the organisation of interest.

Response

Status Response
200 The data (partly deprecated or unused in recent versions of Copper) of the selected Organisation will be returned in a json format.

{

“response_code”:200,

“message”:”Successful”,

“data”:

{

“ID”:”25″,

“Name”:”My Organisation Name”,

…

“Manager”:”1″,

“Colour”:”#82CE4C”,

“url”:”http:\/\/v5.copperhub.com\/index.php?module=people&action=view_organisation&id=25″

}

}

data.Manager: the UserID of the organisations Manager
401 If an ID has been submitted, that does not correspond to a readable organisation with current user rights, a code 401 message will be returned:

{

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

Update Organisation

Update an Organisation.

Request

Method URL           
GET index.php?module=api&v=1&action=update_organisation

 

Required Parameters:

Type Param Value
POST

POST

POST

 session_id

id

data

 string

number

string (json object)

data

The  data  Parameter is the JavaScript representation of the updated organization details.

For example: { Colour: “#ccbbaa”, Name: “My updated Organisation” }

There are no required data attributes, although there should be at least one data attribute defined.

Optional data attributes:

data attribute Value
Name

Colour

Phone1

IM1

IM2

FAX

Address1

Address2

City

State

Country

Postcode

URL

ContactEmail

 string

string (hex color code, #rrggbb)

string

string (Skype)

string (Twitter)

string

string

string

string

string

string

string

string (Website)

string (Email Address)

 

Colour

The Organisation  Colour  in form of a hexadecimal color code.

 

Response

Status Response
200 {

“response_code”:200,

“message”:”The organization has been updated.”,

“data”:

{

“api_version”:1,

“success”:true,

“ID”:”25″

}

}

data.ID: the ID of the updated Organisation
400 {

“response_code”:400,

“message”:”Colour must be a valid hex color code. (like #FFFF00).”,

“data”:

{

“api_version”:1

}

}

Delete Organisation

Delete an Organisation.

Request

Method URL           
GET index.php?module=api&v=1&action=delete_organisation

 

Required Parameters:

Type Param Value
POST

POST

POST

 session_id

confirm_delete

id

 string

number

number

confirm_delete

This parameter should always be set to 1.

Response

Status Response
200 {

“response_code”:200,

“message”:”The organization has been deleted.”,

“data”:

{

“api_version”:1,

“success”:true

}

}
401 {

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

Create Project

Create a new Project.

The Project  Owner will be set to the currently logged in User, if no Owner ID has been provided by the request.

Request

Method URL           
GET index.php?module=api&v=1&action=create_project

 

Required Parameters:

Type Param Value
POST

POST

 session_id

data

 string

string (json object)

data

The  data  Parameter is the JavaScript representation of the new organisation.

For example: { Colour: “#aabbcc”, Name: “My new Organisation” }

Required data Attributes:

data attribute Value
ClientID number

Optional data Attributes:

data attribute Value
Name

Owner

StartDate

EndDate

Status

Colour

Description

Active

 string

number (User ID)

string (i.e. “2013-12-24”)

string (YYYY-mm-dd)

number (0, 1, 2, 3, 4 or 5)

string (hex color code, #rrggbb)

string

number (0 or 1)

 

Colour

The Project  Colour  in form of a hexadecimal color code. If not set, the default colour of #82CE4C will be used.

 

Response

Status Response
200 {

“response_code”:200,

“message”:”The project has been created.”,

“data”:

{

“api_version”:1,

“success”:true,

“ID”:”120″

}

}

data.ID: the ID of the newly created Project
400 {

“response_code”:400,

“message”:”Colour must be a valid hex color code. (like #FFFF00).”,

“data”:

{

“api_version”:1

}

}

 

Read Project

Get all Details of a project corresponding to a given project id.

Request

Method URL           
GET index.php?module=api&v=1&action=read_project

 

Required Parameters:

Type Param Value
POST

POST

 session_id

id

 string

number

id

The  id  of the project of interest.

Response

Status Response
200 The data (partly deprecated or unused in recent versions of Copper) of the selected Project will be returned in a json format.

{

“response_code”:200,

“message”:”Successful”,

“data”:

{

“ID”:”25″,

“Name”:”My Projects Name”,

…

“Colour”:”#82CE4C”,

“PercentComplete”:”80″,       “url”:”http:\/\/v5.copperhub.com\/index.php?module=projects&action=view&projectid=25″

}

}
401 If an ID has been submitted, that does not correspond to a readable organisation with current user rights, a code 401 message will be returned:

{

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

 

Update Project

Update a Project.

Request

Method URL           
GET index.php?module=api&v=1&action=update_project

 

Required Parameters:

Type Param Value
POST

POST

POST

 session_id

id

data

 string

number

string (json object)

data

The  data  Parameter is the JavaScript representation of the updated project details.

For example: { Colour: “#ccbbaa”, Name: “My updated Project” }

There are no required data attributes, although there should be at least one data attribute defined.

Optional data attributes:

data attribute Value
ClientID

Name

Owner

StartDate

EndDate

Colour

Description

Active

 string

string

string

string (yyyy-mm-dd)

string (yyyy-mm-dd)

string (hex color code, #rrggbb)

string

string (0 or 1)

Response

Status Response
200 {

“response_code”:200,

“message”:”The project has been updated.”,

“data”:

{

“api_version”:1,

“success”:true,

“ID”:”125″

}

}

data.ID: the ID of the updated Project
400 {

“response_code”:400,

“message”:”Colour must be a valid hex color code. (like #FFFF00).”,

“data”:

{

“api_version”:1

}

}

Delete Project

Delete a Project.

Request

Method URL           
GET index.php?module=api&v=1&action=delete_project

 

Required Parameters:

Type Param Value
POST

POST

POST

 session_id

confirm_delete

id

 string

number

number

confirm_delete

This parameter should always be set to 1.

Response

Status Response
200 {

“response_code”:200,

“message”:”The project has been deleted.”,

“data”:

{

“api_version”:1,

“success”:true

}

}
401 {

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

 

Create Task

Create a new Task.

The tasks Owner will be set to the currently logged in User, if no Owner ID has been provided by the request.

Request

Method URL           
GET index.php?module=api&v=1&action=create_task

 

Required Parameters:

Type Param Value
POST

POST

 session_id

data

 string

string (json object)

data

The  data  Parameter is the JavaScript representation of the new task.

For example: { ProjectID: 23, Name: “My new Task” }

Required data Attributes:

data attribute Value
ProjectID number

Optional data Attributes:

data attribute Value
Name

Owner

StartDate

EndDate

Duration

Description

TargetBudget

Highlighted

 string

number (User ID)

string (i.e. “2013-12-24”)

string (yyyy-mm-dd)

number (estimated hours)

string

number

number (0 or 1)

 

Response

Status Response
200 {

“response_code”:200,

“message”:”The task has been created.”,

“data”:

{

“api_version”:1,

“success”:true,

“ID”:”423″

}

}

data.ID: the ID of the newly created Task
400 {

“response_code”:400,

“message”:”Highlighted must be 0 or 1.”,

“data”:

{

“api_version”:1

}

}

 

Read Task

Get all details of a task corresponding to the given task id.

Request

Method URL           
GET index.php?module=api&v=1&action=read_task

 

Required Parameters:

Type Param Value
POST

POST

 session_id

id

 string

number

id

The  id  of the task of interest.

Response

Status Response
200 The data of the selected Task will be returned in a json format.

{

“response_code”:200,

“message”:”Successful”,

“data”:

{

“ID”:”7364″,

“Description”:”My Task Description”,

…

“HoursWorked”:”20.00″,

“PercentComplete”:”80″,       “url”:”http:\/\/v5.copperhub.com\/index.php?module=projects&action=taskview&taskid=7364&projectid=121″

}

}
401 If an ID has been submitted, that does not correspond to a readable task with current user rights, a code 401 message will be returned:

{

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

 

Update Task

Update a Task.

Request

Method URL           
GET index.php?module=api&v=1&action=update_task

 

Required Parameters:

Type Param Value
POST

POST

POST

 session_id

id

data

 string

number

string (json object)

data

The  data  Parameter is the JavaScript representation of the updated project details.

For example: { Colour: “#ccbbaa”, Name: “My updated Project” }

There are no required data attributes, although there should be at least one data attribute defined.

Optional data attributes:

data attribute Value
Name

Owner

StartDate

EndDate

Duration

Description

TargetBudget

Highlighted

 string

number (valid person id)

string (yyyy-mm-dd)

string (yyyy-mm-dd)

string (estimated working hours)

string

string

string (0 or 1)

Response

Status Response
200 {

“response_code”:200,

“message”:”The task has been updated.”,

“data”:

{

“api_version”:1,

“success”:true,

“ID”:”6225″

}

}

data.ID: the ID of the updated task
400 {

“response_code”:400,

“message”:”Highlighted must be 0 or 1.”,

“data”:

{

“api_version”:1

}

}

 

Delete Task

Delete a Task.

Request

Method URL           
GET index.php?module=api&v=1&action=delete_task

 

Required Parameters:

Type Param Value
POST

POST

POST

 session_id

confirm_delete

id

 string

number

number

confirm_delete

This parameter should always be set to 1.

Response

Status Response
200 {

“response_code”:200,

“message”:”The task has been deleted.”,

“data”:

{

“api_version”:1,

“success”:true

}

}
401 {

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

Create Task Comment

Create a new Taskcomment.

The taskcomments UserID will be set to the currently logged in User.

Request

Method URL           
GET index.php?module=api&v=1&action=create_taskcomment

 

Required Parameters:

Type Param Value
POST

POST

 session_id

data

 string

string (json object)

data

The  data  Parameter is the JavaScript representation of the new taskcomment.

For example: { TaskID: 5023, Name: “My new Task” }

Required data Attributes:

data attribute Value
ProjectID

Body

 number

string (the comment)

Optional data Attributes:

data attribute Value
HoursWorked

PercentComplete

 number

number

 

Response

Status Response
200 {

“response_code”:200,

“message”:”The taskcomment has been created.”,

“data”:

{

“api_version”:1,

“success”:true,

“ID”:”423″

}

}

data.ID: the ID of the newly created Task
400 {

“response_code”:400,

“message”:”HoursWorked must be a positive Integer.”,

“data”:

{

“api_version”:1

}

}

 

Read Task Comment

Get all details of the taskcomment with a certain task id.

Request

Method URL           
GET index.php?module=api&v=1&action=read_taskcomment

 

Required Parameters:

Type Param Value
POST

POST

 session_id

id

 string

number

id

The  id  of the taskcomment of interest.

Response

Status Response
200 The data of the selected Taskcomment will be returned in a json format.

{

“response_code”:200,

“message”:”Successful”,

“data”:

{

“ID”:”3″,

“Description”:”Everything done.”,

…

“HoursWorked”:”20.00″,

“PercentComplete”:”100″,

“TaskID”:”123″

}

}
401 If an ID has been submitted, that does not correspond to a readable taskcomment with current user rights, a code 401 message will be returned:

{

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

Delete Task Comment

Delete a Taskcomment. Only Copper admins are able to make use of this Interface.

Request

Method URL           
GET index.php?module=api&v=1&action=delete_taskcomment

 

Required Parameters:

Type Param Value
POST

POST

POST

 session_id

confirm_delete

id

 string

number

number

confirm_delete

This parameter should always be set to 1.

Response

Status Response
200 {

“response_code”:200,

“message”:”The taskcomment has been deleted.”,

“data”:

{

“api_version”:1,

“success”:true

}

}
401 {

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

Get All Projects of Current User

Get a list of all projects that the current user has access to. The user will be authenticated using the session_id.

Request

Method URL           
GET index.php?module=api&v=1&action=get_projects

 

Required Parameters:

Type Param Value
POST session_id string

Response

Status Response
200 {

“response_code”:200,

“message”:”Successful.”,

“data”:

{

“api_version”:1,

“success”:true,

“projects”:

{

“1”:

{

“ID”:”1″,

“Name”:”My First Project”,

…

“Description”:”Here is a project to get you started with Copper.”

},

“2”:

{ … }

}

}

}
401 {

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

 

Get All Accessible Organizations

Get a list of all organisations that the current user has access to.

Request

Method URL           
GET index.php?module=api&v=1&action=get_organisations

 

Required Parameters:

Type Param Value
POST session_id string

Response

Status Response
200 {

“response_code”:200,

“message”:”Successful.”,

“data”:

{

“api_version”:1,

“success”:true,

“organisations”:

{

“1”:

{

“ID”:”1″,

“Name”:”Demo Organisation”,

…

“State”:”Victoria”

},

“2”:

{ … }

}

}

}
401 {

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

 

Get All Tasks for a Project

Get a list of all tasks of a project.

Request

Method URL           
GET index.php?module=api&v=1&action=get_project_tasks

 

Required Parameters:

Type Param Value
POST

POST

 session_id

id

 string

number

id

The ID of the project.

Response

Status Response
200 {

“response_code”:200,

“message”:”Successful.”,

“data”:

{

“api_version”:1,

“success”:true,

“taskcomments”:

{

“449”:

{

“ID”:”449″,

“Subject”:”All done.”,

…

“HoursWorked”:”4.00″

},

“450”:

{ … }

}

}

}
401 {

“response_code”:401,

“message”:”Unauthorized”,

“data”:

{

“api_version”:1

}

}

Conventions

  1. Status – HTTP status code of response.
  2. All responses are in JSON format.
  3. The Copper API must be enabled in general Copper settings

 

Status Codes

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX – Success of some kind

4XX – Error occurred in client’s part

5XX – Error occurred in server’s part

Status Code Description
200 OK
400 Bad request
401 Unauthorized
500 Internal Server Error
501 Not Implemented
503 Service Unavailable

 

Most Popular
logo

Element Software, Inc. is based in Texas. We have been developing software products since 1999, our flagship product, Free Subscription Copper Project, being launched in 2001.

Copyright Copperproject.com.com | 2019 All Rights Reserved