Work Orders

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

Purpose:
The Work Orders API allows you to manage project work orders via microservices and external applications. It supports creating new work orders, updating existing ones, closing work orders, and retrieving work order information.

Base URL:
/v1/work-orders

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/work-orders`	Create a single work order record	Only 1 work order per call. Supports auto-numbering.
GET	`/v1/work-orders/{workOrderId}`	Retrieve single work order data	Supports optional company filter. Returns complete work order information.
PATCH	`/v1/work-orders/{workOrderId}`	Update work order data	One work order per call, multiple fields can be updated.
DELETE	`/v1/work-orders/{workOrderId}`	Close (soft-delete) a work order	Changes status to ‘Closed’.

Swagger / Schema

Version v1

Method Details

Sample Request

{
  "companyId": "COMP1",
  "dateFrom": "2001-01-01",
  "costCentre": "C1",
  "workOrderName": "NewWorkOrder",
  "periodFrom": 200101,
  "periodTo": 200153,
  "projectId": "ProId1",
  "projectManagerId": "33225",
  "status": "N",
  "workOrderId": "123",
  "customerInformation": {
    "currencyCode": "GBP"
  },
  "relatedValues": [
    {
      "relationId": "C1",
      "relatedValue": "100",
      "dateFrom": "1900-01-01",
      "dateTo": "2099-12-31"
    }
  ]
}

Note: The workOrderId field is optional. When not provided, the system will auto-generate a work order ID based on configured numbering series.

Default Values

During the posting process, some fields are auto-completed by the API when they are empty:

Standard Fields:

serviceOrder: Default = false
periodFrom: Default = period related to dateFrom date
periodTo: Default = period related to dateTo date

Customer Information:

customerInformation.invoiceSeparately: Default = false
customerInformation.invoiceStatus: Default = T (not billable)

Related Values:

relationId B0 (Project attribute Id): Default = same value as projectId
relationId C0 (Resource/Employee attribute Id): Default = same value as projectManagerId

When customerId is provided:

customerInformation.reference: Auto-populated with the name of the contact person for the customer

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 work order 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 work order needs to be created
WHEN	Calling the POST method of the API
BUT	A mandatory field is missing
THEN	Work order 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}.” / “This number series requires a relation value for {0}. Please enter the relation value.”

POST_003 - Invalid format of fields

Element	Details
Scenario ID	POST_003
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	A new work order needs to be created
WHEN	Calling the POST method of the API
BUT	Field format is invalid
THEN	Work order 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 work order needs to be created
WHEN	Calling the POST method of the API
BUT	Field violates model restrictions (length, range, numeric limits)
THEN	Work order 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 workOrderId

Element	Details
Scenario ID	POST_005
Scenario Name	Duplicate workOrderId
HTTP Code	422
GIVEN	A new work order needs to be created
WHEN	Calling the POST method of the API
BUT	workOrderId already exists within companyId
THEN	Work order is not created; 422 response is returned
Example Error Message	“The work order already exists.”

POST_006 - Invalid data

Element	Details
Scenario ID	POST_006
Scenario Name	Invalid data
HTTP Code	422
GIVEN	A new work order 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	Work order is not created; 422 response is returned
Example Error Message	“{0} is not a legal {1}” / “Illegal {0}”

POST_007 - Work order created

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

POST_008 - Work order created with auto-numbering

Element	Details
Scenario ID	POST_008
Scenario Name	Work order created with auto-numbering
HTTP Code	201
GIVEN	A new work order needs to be created
WHEN	Calling the POST method of the API
BUT	workOrderId is not provided
THEN	A new work order is created with auto-generated workOrderId
Example Error Message	RESPONSE: returns the created work order with new workOrderId (auto-numbering)

Sample Request

GET /v1/projects/work-orders/123?companyId=COMP1

Additional Parameters

The following parameters help retrieve basic information about a work order:

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

Validation Rules for GET Method

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 work order 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 work order 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 work order needs to be retrieved
WHEN	Calling the GET method of the API
BUT	workOrderId is not indicated
THEN	Work order is not retrieved; 405 response is returned
Example Error Message	(Empty message)

GET_004 - workOrderId does not exist

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

GET_005 - Work order exists

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

Sample Request

[{
  "path": "/",
  "op": "Replace",
  "value": {
    "workOrderName": "Updated Work Order Name",
    "status": "C",
    "probability": 70
  }
}]

[{
  "path": "/workOrderName",
  "op": "Replace",
  "value": "New name"
}]

Additional Parameters

The following parameters help update basic information about a work order:

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

Limits & Notes

One work order per call.
Possibility to update several fields per call.
Patch operators available: Replace, Add, Remove

Supported Operations

The PATCH endpoint supports the following JSON Patch operations:

Operation	Description	Use Case
Replace	Replaces existing value	Update existing fields
Add	Adds new value to array/object	Add new array elements or properties
Remove	Removes value	Delete array elements or optional properties

Validation Rules for PATCH Method

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 work order
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 work order
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 work order
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 work order
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 workOrderId

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

Sample Request

DELETE /v1/projects/work-orders/123?companyId=COMP1

Additional Parameters

The following parameters help to delete a work order:

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

Limits & Notes

Changes the status of a work order to “Closed”.
Does not permanently delete the work order.
If you need to update the status to something other than “Closed”, 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	Work order 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	Work order 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 - Work order does not exist

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

DEL_004 - Work order exists

Element	Details
Scenario ID	DEL_004
Scenario Name	Work order exists
HTTP Code	200
GIVEN	Work order needs to be ‘Closed’
WHEN	Calling DELETE method of the API
BUT	—
THEN	Work order is ‘Closed’; 200 response is returned
Example Error Message or Response	(Empty message - no content)

Best Practices

Use Swagger UI for testing and schema validation before production calls.
Handle error codes gracefully - implement retry/backoff logic according to global rate limits.
Always check for deprecation alerts on this endpoint version.
Leverage auto-numbering when creating work orders without specifying workOrderId to ensure unique identifiers.
Understand default values - many fields are auto-populated during POST operations to simplify integration.
Use PATCH for status updates other than “Closed” - the DELETE endpoint only sets status to “Closed”.

ERPx

ERPx

U4 ERPx

Work Orders

The Work Orders API in Unit4 ERPx manages project work order data - creation, retrieval, updates, and closure (soft-delete) of work order 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

Default Values

Validation Rules for POST Method

Sample Request

Additional Parameters

Validation Rules for GET Method

Sample Request

Additional Parameters

Limits & Notes

Supported Operations

Validation Rules for PATCH Method

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for DELETE Method

Best Practices

Action APIs

Query APIs (Read-Only)

U4 ERPx

Work Orders

The Work Orders API in Unit4 ERPx manages project work order data - creation, retrieval, updates, and closure (soft-delete) of work order 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

Default Values

Validation Rules for POST Method

Sample Request

Additional Parameters

Validation Rules for GET Method

Sample Request

Additional Parameters

Limits & Notes

Supported Operations

Validation Rules for PATCH Method

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for DELETE Method

Best Practices

Related endpoints

Action APIs

Projects

Assignments

Billing price list prices

Query APIs (Read-Only)

Connection per work order