Projects

The Project API in Unit4 ERPx manages project-related data - creation, retrieval, updates, and termination (soft-delete) of project records. It is designed for integration with mobile and other external applications, supporting microservice-based development, testing, and maintenance.

Purpose:
The Project API manages all aspects of project data, including creation, update, validation, and soft deletion (termination).

Base URL:
/v1/projects

Authentication:
All APIs require a Client ID and Client Secret.
Refer to the global authentication documentation for details.

System Parameters:
System parameters for this API are available in Online Help → Project Management → Project Information → Fixed Registers → System Parameters.

Supported Methods

HTTP Method	Endpoint	Description	Limits & Notes
POST	`/v1/projects`	Create a single project record	Only 1 project per call.
GET	`/v1/projects/{projectId}`	Retrieve single project data	Supports optional company filter. Response contains project relations, flexi-fields, billing information, activities, global projects, and work orders.
GET	`/v1/projects/portfolio`	Retrieve portfolio of projects	Returns list of projects managed by currently logged user.
PATCH	`/v1/projects/{projectId}`	Update project data	Allows modifying project records. One project per call, multiple fields can be updated.
DELETE	`/v1/projects/{projectId}`	Terminate (soft-delete) a project	Changes status to ‘Closed’.

Swagger / Schema

Version v1

Method Details

Sample Request

{
  "postTimeCosts": true,
  "companyId": "EN",
  "authorisation": "N",
  "costCentre": "410",
  "projectName": "Project Name RR1",
  "mainProject": "RR1",
  "probability": 0,
  "projectId": "RR1",
  "projectManagerId": "87010101",
  "status": "N",
  "projectType": "IN",
  "containsWorkOrders": true
}

Validation Rules for POST Method

POST_001 - User is not authorised

Element	Details
Scenario ID	POST_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	A new project needs to be created
WHEN	Calling the POST method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_002 - Missing mandatory fields

Element	Details
Scenario ID	POST_002
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	A new project needs to be created
WHEN	Calling the POST method of the API
BUT	A mandatory field is missing
THEN	Project is not created; 422 response is returned
Example Error Message	“The {0} field is required.” / “Illegal value entered” / “A value must be entered for {0}.”

POST_003 - Invalid format of fields

Element	Details
Scenario ID	POST_003
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	A new project needs to be created
WHEN	Calling the POST method of the API
BUT	Field format is invalid
THEN	Project is not created; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…” / “The field {0} must be between 0 and 100.”

POST_004 - Unsatisfied model restrictions

Element	Details
Scenario ID	POST_004
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	A new project needs to be created
WHEN	Calling the POST method of the API
BUT	Field violates model restrictions (length, range, numeric limits)
THEN	Project is not created; 422 response is returned
Example Error Message	“The field {0} must be a string with max length {1}” / “{0} must be equal or earlier than {1}”

POST_005 - Duplicate projectId

Element	Details
Scenario ID	POST_005
Scenario Name	Duplicate projectId
HTTP Code	422
GIVEN	A new project needs to be created
WHEN	Calling the POST method of the API
BUT	projectId already exists within companyId
THEN	Project is not created; 409 response is returned
Example Error Message	“{0} already exists.”

POST_006 - Invalid data

Element	Details
Scenario ID	POST_006
Scenario Name	Invalid data
HTTP Code	422
GIVEN	A new project needs to be created
WHEN	Calling the POST method of the API
BUT	Data does not exist on ERP (attribute values, list of possible values)
THEN	Project is not created; 422 response is returned
Example Error Message	“{0} is not a legal {1}” / “Illegal {0}”

POST_007 - Project created

Element	Details
Scenario ID	POST_007
Scenario Name	Project created
HTTP Code	201
GIVEN	A new project needs to be created
WHEN	Calling the POST method of the API
BUT	—
THEN	A new project is created
Example Error Message	RESPONSE: returns the created project

Sample Request

GET /projects/123

Additional Parameters

The following parameters help retrieve basic information about a project:

Parameter	Value	Description	Data Type	Default Value
companyId	optional	Specify if you wish to retrieve a project that exists in a specific company or client.	string	empty

Validation Rules for GET Method (projectId)

GET_001 - User is not authorised

Element	Details
Scenario ID	GET_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Data from an existing project needs to be retrieved
WHEN	Calling the GET method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

GET_002 - Unknown companyID

Element	Details
Scenario ID	GET_002
Scenario Name	Unknown companyID
HTTP Code	403
GIVEN	Data from an existing project needs to be retrieved
WHEN	Calling the GET method of the API
BUT	companyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

GET_003 - Missing mandatory fields

Element	Details
Scenario ID	GET_003
Scenario Name	Missing mandatory fields
HTTP Code	405
GIVEN	Data from an existing project needs to be retrieved
WHEN	Calling the GET method of the API
BUT	projectId is not indicated
THEN	Project is not retrieved; 405 response is returned
Example Error Message	(Empty message)

GET_004 - projectId does not exist

Element	Details
Scenario ID	GET_004
Scenario Name	projectId does not exist
HTTP Code	404
GIVEN	Data from an existing project needs to be retrieved
WHEN	Calling the GET method of the API
BUT	projectId does not exist for the companyId
THEN	Project is not retrieved; 404 response is returned
Example Error Message	“The entity of the following parameters [Company: {0}, Project: {1}] was not found.”

GET_005 - Project exists

Element	Details
Scenario ID	GET_005
Scenario Name	Project exists
HTTP Code	200
GIVEN	Data from an existing project needs to be retrieved
WHEN	Calling the GET method of the API
BUT	—
THEN	200 response is returned together with the information of the project
Example Error Message	RESPONSE: Project information is retrieved

Sample Request

N/A

Additional Parameters

The following parameters help retrieve basic information about projects:

Parameter	Value	Description	Data Type	Default Value
companyId	optional	Specify if you wish to retrieve a project that exists in a specific company or client.	string	empty

Limits & Notes

It is not possible to request projects that belong to another user.
The response code will be 200 regardless of whether the user is not a Project manager of any Project OR if they are the Project manager of a Project with the status “Closed” or “Terminated”.

Validation Rules for GET Method (Portfolio)

GET_001 - User is not authorised

Element	Details
Scenario ID	GET_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	User needs to know which project they run as a Project manager
WHEN	Calling the GET method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

GET_002 - User does not have any project assigned

Element	Details
Scenario ID	GET_002
Scenario Name	User does not have any project assigned
HTTP Code	200
GIVEN	User needs to know which project they run as a Project manager
WHEN	Calling the GET method of the API
BUT	Connected user does not have a project assigned
THEN	200 response is returned with an empty list
Example Error Message	[]

GET_003 - User is the Project manager of a Project with "Closed" or "Terminated" status

Element	Details
Scenario ID	GET_003
Scenario Name	User is the Project manager of a Project with “Closed” or “Terminated” status
HTTP Code	200
GIVEN	User needs to know which project they run as a Project manager
WHEN	Calling the GET method of the API
BUT	Connected user does not have an “Active” project assigned
THEN	200 response is returned with an empty list
Example Error Message	[]

GET_004 - User is the Project manager of at least one Project with "Active" status

Element	Details
Scenario ID	GET_004
Scenario Name	User is the Project manager of at least one Project with “Active” status
HTTP Code	200
GIVEN	User needs to know which project they run as a Project manager
WHEN	Calling the GET method of the API
BUT	Connected user is the Project manager of at least one project
THEN	200 response is returned together with the basic information of all projects where the user is the Project manager
Example Error Message	RESPONSE: List of projects is retrieved

GET_005 - User is the Project manager of several projects and one has "Closed" or "Terminated" status

Element	Details
Scenario ID	GET_005
Scenario Name	User is the Project manager of several projects and one has “Closed” or “Terminated” status
HTTP Code	200
GIVEN	User needs to know which project they run as a Project manager
WHEN	Calling the GET method of the API
BUT	One of the projects has the status “Closed” or “Terminated”
THEN	200 response is returned together with the basic information of all projects where the user is the Project manager, and the project status is not “Closed” or “Terminated”
Example Error Message	RESPONSE: List of projects is retrieved

Sample Request

{
  "path": "/",
  "op": "Replace",              
  "value": {
    "projectName": "Enter your name here",
    "status": "C",
    "probability": 70
  }
}

{
  "path": "/customFieldGroups/oppor/status_fx",
  "op": "Replace",              
  "value": "Chance higher than 79%"
}

Additional Parameters

The following parameters help retrieve or update basic information about a project:

Parameter	Value	Description	Data Type	Default Value
companyId	optional	Specify if you wish to update a project that exists in a specific company or client.	string	empty

Limits & Notes

One project per call.
Possibility to update several fields per call.

Validation Rules for PATCH Method (projectId)

PATCH_001 - User is not authorised

Element	Details
Scenario ID	PATCH_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	User needs to modify existing project
WHEN	Calling PATCH method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 response is returned
Example Error Message	“User is not authorised.”

PATCH_002 - Missing mandatory fields

Element	Details
Scenario ID	PATCH_002
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	User needs to modify existing project
WHEN	Calling PATCH method of the API
BUT	Mandatory field is missing
THEN	Data is not updated; 422 response is returned
Example Error Message	“The {0} field is required.”

PATCH_003 - Invalid format of fields

Element	Details
Scenario ID	PATCH_003
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	User needs to modify existing project
WHEN	Calling PATCH method of the API
BUT	Field format is invalid
THEN	Data is not updated; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…”

PATCH_004 - Unsatisfied model restrictions

Element	Details
Scenario ID	PATCH_004
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	User needs to modify existing project
WHEN	Calling PATCH method of the API
BUT	Field violates model restrictions
THEN	Data is not updated; 422 response is returned
Example Error Message	“The date must be between {0} and {1}” / “The field {0} must be a string with max length {1}”

PATCH_006 - Unknown projectId

Element	Details
Scenario ID	PATCH_006
Scenario Name	Unknown projectId
HTTP Code	404
GIVEN	User needs to modify existing project
WHEN	Calling PATCH method of the API
BUT	projectId does not exist
THEN	Data is not updated; 404 response is returned
Example Error Message	“Project with ID {0} was not found within the company {1}.”

Sample Request

DELETE projects/123

Additional Parameters

The following parameters help to delete a project:

Parameter	Value	Description	Data Type	Default Value
companyId	optional	Specify if you wish to delete a project that exists in a specific company or client.	string	empty

Limits & Notes

Change the status of a Project to “Closed”.
If you’re looking to update the project status to something other than “Closed”, you can use the PATCH endpoint.

Validation Rules for DELETE Method

DEL_001 - User is not authorised

Element	Details
Scenario ID	DEL_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Project needs to be “Closed”
WHEN	Calling DELETE method of the API
BUT	User is not authorised
THEN	API is not reached; 403 response is returned
Example Error Message or Response	“User is not authorised.”

DEL_002 - Missing required parameters

Element	Details
Scenario ID	DEL_002
Scenario Name	Missing required parameters
HTTP Code	405
GIVEN	Project needs to be “Closed”
WHEN	Calling DELETE method of the API
BUT	Required parameter is missing
THEN	API is not reached; 405 response is returned
Example Error Message or Response	Empty message

DEL_003 - Project does not exist

Element	Details
Scenario ID	DEL_003
Scenario Name	Project does not exist
HTTP Code	404
GIVEN	Project needs to be “Closed”
WHEN	Calling DELETE method of the API
BUT	projectId does not exist
THEN	No deletion; 404 response is returned
Example Error Message or Response	“Project with Id {0} was not found within company {1}”

DEL_004 - Project exists

Element	Details
Scenario ID	DEL_004
Scenario Name	Project exists
HTTP Code	200
GIVEN	Project needs to be “Closed”
WHEN	Calling DELETE method of the API
BUT
THEN	Project is “Closed”; 200 response is returned
Example Error Message or Response	Empty message

Best Practices

Use Swagger UI for testing and schema validation before production calls.
Handle error codes gracefully; implement retry/backoff according to global rate limits.
Always check for deprecation alerts on this endpoint version.
Validate projects before sending DELETE requests to avoid unintentional data loss.

ERPx

ERPx

U4 ERPx

Projects

The Project API in Unit4 ERPx manages project-related data - creation, retrieval, updates, and termination (soft-delete) of project records. It is designed for integration with mobile and other external applications, supporting microservice-based development, testing, and maintenance.

Supported Methods

Swagger / Schema

Version v1

Method Details

Sample Request

Validation Rules for POST Method

Sample Request

Additional Parameters

Validation Rules for GET Method (projectId)

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for GET Method (Portfolio)

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for PATCH Method (projectId)

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for DELETE Method

Best Practices

Action APIs

Query APIs (Read-Only)

U4 ERPx

Projects

The Project API in Unit4 ERPx manages project-related data - creation, retrieval, updates, and termination (soft-delete) of project records. It is designed for integration with mobile and other external applications, supporting microservice-based development, testing, and maintenance.

Supported Methods

Swagger / Schema

Version v1

Method Details

Sample Request

Validation Rules for POST Method

Sample Request

Additional Parameters

Validation Rules for GET Method (projectId)

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for GET Method (Portfolio)

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for PATCH Method (projectId)

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for DELETE Method

Best Practices

Related endpoints

Action APIs

Work orders

Assignments

Revenue recognition

Billing price list prices

Invoice base

Query APIs (Read-Only)

Connections per project

Hourly costs