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

MethodURL
POSTindex.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.

TypeParamValue
POSTPOSTusernamepasswordstringstring

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

StatusDescription
200Sent, 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.

400Sent, when username is missing.{“response_code”:400,”message”:”Bad Request”,

“data”:

{

“api_version”:1

}

}

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

“data”:

{

“api_version”:1

}

}

Request

MethodURL           
POSTindex.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.

TypeParamValue
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

StatusDescription
200Sent, 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.

400Sent, when username is missing.

{

“response_code”:400,

“message”:”Bad Request”,

“data”:

{

“api_version”:1

}

}

401Sent, 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

MethodURL           
POSTindex.php?module=api&v=1&action=check_session

 

TypeParamValue
POSTsession_idstring

session_id

The  session_id  that was given in response to Login

Response

StatusResponse
200In 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

MethodURL           
POSTindex.php?module=api&v=1&action=logout

 

TypeParamValue
POSTsession_idstring

 

session_id

The  session_id  that was given in response to Login

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=create_organisation

 

Required Parameters:

TypeParamValue
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 attributeValue
Namestring

Optional data Attributes:

data attributeValue
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

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=read_organisation

 

Required Parameters:

TypeParamValue
POST

POST

session_id

id

string

number

id

The  id  of the organisation of interest.

Response

StatusResponse
200The 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

401If 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

MethodURL           
GETindex.php?module=api&v=1&action=update_organisation

 

Required Parameters:

TypeParamValue
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 attributeValue
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

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=delete_organisation

 

Required Parameters:

TypeParamValue
POST

POST

POST

session_id

confirm_delete

id

string

number

number

confirm_delete

This parameter should always be set to 1.

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=create_project

 

Required Parameters:

TypeParamValue
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 attributeValue
ClientIDnumber

Optional data Attributes:

data attributeValue
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

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=read_project

 

Required Parameters:

TypeParamValue
POST

POST

session_id

id

string

number

id

The  id  of the project of interest.

Response

StatusResponse
200The 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″

}

}

401If 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

MethodURL           
GETindex.php?module=api&v=1&action=update_project

 

Required Parameters:

TypeParamValue
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 attributeValue
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

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=delete_project

 

Required Parameters:

TypeParamValue
POST

POST

POST

session_id

confirm_delete

id

string

number

number

confirm_delete

This parameter should always be set to 1.

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=create_task

 

Required Parameters:

TypeParamValue
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 attributeValue
ProjectIDnumber

Optional data Attributes:

data attributeValue
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

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=read_task

 

Required Parameters:

TypeParamValue
POST

POST

session_id

id

string

number

id

The  id  of the task of interest.

Response

StatusResponse
200The 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″

}

}

401If 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

MethodURL           
GETindex.php?module=api&v=1&action=update_task

 

Required Parameters:

TypeParamValue
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 attributeValue
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

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=delete_task

 

Required Parameters:

TypeParamValue
POST

POST

POST

session_id

confirm_delete

id

string

number

number

confirm_delete

This parameter should always be set to 1.

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=create_taskcomment

 

Required Parameters:

TypeParamValue
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 attributeValue
ProjectID

Body

number

string (the comment)

Optional data Attributes:

data attributeValue
HoursWorked

PercentComplete

number

number

 

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=read_taskcomment

 

Required Parameters:

TypeParamValue
POST

POST

session_id

id

string

number

id

The  id  of the taskcomment of interest.

Response

StatusResponse
200The 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″

}

}

401If 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

MethodURL           
GETindex.php?module=api&v=1&action=delete_taskcomment

 

Required Parameters:

TypeParamValue
POST

POST

POST

session_id

confirm_delete

id

string

number

number

confirm_delete

This parameter should always be set to 1.

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=get_projects

 

Required Parameters:

TypeParamValue
POSTsession_idstring

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=get_organisations

 

Required Parameters:

TypeParamValue
POSTsession_idstring

Response

StatusResponse
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

MethodURL           
GETindex.php?module=api&v=1&action=get_project_tasks

 

Required Parameters:

TypeParamValue
POST

POST

session_id

id

string

number

id

The ID of the project.

Response

StatusResponse
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 CodeDescription
200OK
400Bad request
401Unauthorized
500Internal Server Error
501Not Implemented
503Service Unavailable