Proteus Logo

Proteus Public API (1.0.2)

Download OpenAPI specification:

Publicly available API endpoints to Proteus

Company

Company-related endpoints

List companies

Authorizations:
OAuth2
query Parameters
type
string
Enum: "supplier" "client" "subcontractor" "3rd_party" "agency" "internal"

List companies matching a single type.

include
string
Default: "basic"
Enum: "all" "basic"

Choose between including all parameters or only the basic ones in the request. All parameters includes staff_rep, contacts and offices.

page
integer

The page number to retrieve items from the result set.

per_page
integer

The numbers of items to return

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Get company by ID

Authorizations:
OAuth2
path Parameters
id
required
integer

Company ID

query Parameters
include
string
Default: "basic"
Enum: "all" "basic"

Choose between including all parameters or only the basic ones in the request. All parameters includes staff_rep, contacts and offices.

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Get related company office(s)

Authorizations:
OAuth2
path Parameters
id
required
integer

Company ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get related company contact(s)

Authorizations:
OAuth2
path Parameters
id
required
integer

Company ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update company metadata by ID

Authorizations:
OAuth2
path Parameters
id
required
integer

Company ID

Request Body schema: application/json
required

Request body for the metadata

metadata_key
string

Metadata key and value

Responses

Request samples

Content type
application/json
{
  • "metadata_key": "{value}"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Contact

Contact-related endpoints

Update or Create Company Contact

Authorizations:
OAuth2
Request Body schema: application/json
required

Request body for expenses

Array of objects
name
string
company_id
required
integer
job_title
string
email
required
string <email>
telephone
string
mobile
string

Responses

Request samples

Content type
application/json
{
  • "metadata": [
    ],
  • "name": "James Smith",
  • "company_id": 1,
  • "job_title": "Software Engineer",
  • "email": "james.smith@example.com",
  • "telephone": "1234567890",
  • "mobile": "0987654321"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Proposal

Proposal-related endpoints

List Proposals

Authorizations:
OAuth2
query Parameters
include
string
Default: "basic"
Enum: "all" "basic"

Choose between including all parameters or only the basic ones in the request. All parameters includes staff_rep, contacts and offices.

active
boolean

Filter the list based on the active status. Set this parameter to true to retrieve active items, or false to retrieve inactive items.

page
integer

The page number to retrieve items from the result set.

per_page
integer

The numbers of items to return

date_won_from
string
Example: date_won_from=2023-01-01

Filter proposals to those that have been won, starting from this date

date_won_to
string
Example: date_won_to=2023-01-01

Filter proposals to those that have been won, before this date. date_sent_from is required for this to take effect

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Get proposal by ID

Authorizations:
OAuth2
path Parameters
id
required
integer

Proposal ID

query Parameters
include
string
Default: "basic"
Enum: "all" "basic"

Choose between including all parameters or only the basic ones in the request. All parameters includes budget, office, manager, company, company_contact and contract.

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Project

Project-related endpoints

List Projects

Authorizations:
OAuth2
query Parameters
include
string
Default: "basic"
Enum: "all" "basic"

Choose between including all parameters or only the basic ones in the request. All parameters includes staff_rep, contacts and offices.

active
boolean

Filter the list based on the active status. Set this parameter to true to retrieve active items, or false to retrieve inactive items.

page
integer

The page number to retrieve items from the result set.

per_page
integer

The numbers of items to return

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Get project by ID or Reference

Authorizations:
OAuth2
path Parameters
required
integer or string

Project ID / Reference

query Parameters
usingReference
boolean

Optional Flag to find project by reference (0 = false, 1 = true)

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Get project by ID with outgoing purchase order

Authorizations:
OAuth2
path Parameters
required
integer or string

Project ID / Reference

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Outgoing Purchase Order Receipt by ID

Authorizations:
OAuth2
path Parameters
id
required
integer

Outgoing Purchase Order Receipt ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Work Package

Work Package Tree related endpoint

Get Work Package Tree

Authorizations:
OAuth2
path Parameters
id
required
integer

Work Package ID

query Parameters
max_depth
integer [ 1 .. 20 ]
Default: 10

The maximum depth of the tree to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Variation

Variation-related endpoint

List Variations

Authorizations:
OAuth2
query Parameters
status
string
Enum: "draft" "in-review" "in-review" "internally-approved" "rejected" "issued" "approved"

Status of the variations to retrieve.

root_work_package
integer

Limit the variations only to a single root work package id.

page
integer

The page number to retrieve items from the result set.

per_page
integer

The numbers of items to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get variation by ID

Authorizations:
OAuth2
path Parameters
id
required
integer

Variation ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Staff

Staff-related endpoints

Create/Update a staff user

This API endpoint allows you to create or update a staff user based on their external reference. If the user with the provided external reference exists, the endpoint will update their information; otherwise, it will create a new user.

Authorizations:
OAuth2
Request Body schema: application/json
required

Request body for staff

reference
required
string

A unique reference string for the user. E.g. Application Staff ID

external_reference
required
string

A secondary reference to match with your application. Proteus will match using the external_reference E.g. GUID

first_name
required
string

First name

last_name
required
string

Last name

email
required
string

Email address (should be unique)

required
object

Match with either id or name

required
object

Match with either id or name

required
object

Match with either id or name

required
object

Match with either id or name

job_title
string

Job title

contact_no
string

Contact number

location
string

Location/city

employment_type
string
Default: "staff-fulltime"
Enum: "staff-fulltime" "staff-parttime" "contract" "freelance"

Employment type

user_role
string
Default: "offline"
Enum: "offline" "company-admin" "company-manager" "office-manager" "manager" "user" "timesheet-only-user"

User sccess role

cost
number
Default: 0

Cost per hour

expected_weekly_hours
number
Default: 40

Expected hours per week.

object

Match with either id or external_reference

object
active
boolean
Default: true

Make a staff profile active or inactive (only for offline user)

object

Responses

Request samples

Content type
application/json
{
  • "reference": "5_DIGIT",
  • "external_reference": "External-GUID",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john.doe@xergy.com",
  • "job_title": "Senior Engineer",
  • "contact_no": "12345678",
  • "location": "Aberdeenshire",
  • "employment_type": "staff-fulltime",
  • "user_role": "manager",
  • "cost": 250,
  • "expected_weekly_hours": 40,
  • "department": {
    },
  • "grade": {
    },
  • "discipline": {
    },
  • "office": {
    },
  • "manager": {
    },
  • "profile": {
    },
  • "custom_fields": {
    },
  • "active": true
}

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Timesheet

Timesheet-related endpoints

Get timesheets within range

Authorizations:
OAuth2
query Parameters
date_from
required
string <date>
Example: date_from=2023-01-12

Date in Y-m-d

date_to
required
string <date>
Example: date_to=2023-01-19

Date in Y-m-d

approved
boolean
Example: approved=true

Boolean flag to only include approved timesheets

discipline
string
Example: discipline=Developer

Filter user timesheets by discipline

timesheet_id
integer
Example: timesheet_id=55

Get a single timesheet by id

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create or Update timesheets

Authorizations:
OAuth2
Request Body schema: application/json
required

Request body for timesheet

Array of objects (TimesheetEntry)

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": "Timesheets created/updated"
}

Expense

Expense-related endpoints

Create an Expense

Authorizations:
OAuth2
Request Body schema: application/json
required

Request body for expenses

user_email
required
string

Email address of the user attached to the expense

expense_type
required
string
Value: "labour"

Expense Type

project_reference
string

Project reference required if billable is true

work_package_reference
string

Workpackage reference

dated
required
string

The date of the expense in YYYY-MM-DD format

billable
required
boolean

A boolean flag if the expense is billable

comment
required
string

A comment attached to the expense

rate
required
integer

The expense rate

quantity
required
string

quantity of the expense

type
required
string
Enum: "Direct" "Paid by me"

Finance Type

notes
required
string

Expense notes

status
required
string
Enum: "approved" "draft" "reopen" "pending"

Expense status

Responses

Request samples

Content type
application/json
{
  • "user_email": "james.smith@example.com",
  • "expense_type": "labour",
  • "project_reference": "J-HO-00001",
  • "work_package_reference": "100",
  • "dated": "2023-03-15",
  • "billable": true,
  • "comment": "This is a comment",
  • "rate": 35,
  • "quantity": 4,
  • "type": "Direct",
  • "notes": "Example notes",
  • "status": "approved"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Invoice

Invoice-related endpoints

Get invoice by ID

Authorizations:
OAuth2
path Parameters
id
required
integer

Invoice ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}