Customers

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

Purpose:
This API is used to create and maintain customers within ERPx.

Base URL:
/v1/customers

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 → Sales → Customer Management → Fixed Registers → System Parameters.

Supported Methods

HTTP Method	Endpoint	Description	Limits & Notes
GET	`/v1/customers/{customerId}`	Retrieve single customer data	Returns the whole object for a given customer ID / company ID. Only a single customer is returned – for more results please use the object API.
POST	`/v1/customers`	Create a single customer record	Only 1 customer per call. Can create with auto-numbering.
PATCH	`/v1/customers/{customerId}`	Update customer data	Allows patch operations on a customer. Only a single customer can be patched, but multiple operations may be made in a single request.
DELETE	`/v1/customers/{customerId}`	Terminate (soft-delete) a customer	Changes status to ‘Closed’. Does not delete the customer permanently. The operation may be undone with a Replace operation through the PATCH endpoint on the path “/payment/status”.

Swagger / Schema

Version v1

Method Details

Sample Request

{
GET /v1/customers/11000002?companyId=EN
}

Validation Rules for GET Method – Single

GET_001 - Invalid authorisation

Element	Details
Scenario ID	GET_001
Scenario Name	Invalid authorisation
HTTP Code	401
GIVEN	The token provided does not pass authorisation
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 401 error and a message
Example Error Message	`{"statusCode": 401, "message": "Invalid JWT."}`

GET_002 - User is not authorised to access API

Element	Details
Scenario ID	GET_002
Scenario Name	User is not authorised to access API
HTTP Code	403
GIVEN	The user is not authorised to access the API
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 403 error and a message
Example Error Message	`{"code": 2030, "message": "User is not authorized"}`

GET_003 - Missing mandatory parameter

Element	Details
Scenario ID	GET_003
Scenario Name	Missing mandatory parameter
HTTP Code	405
GIVEN	The user does not provide a customerId for the request
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 405 error
Example Error Message	`405 Method Not Allowed`

GET_004 - Customer does not exist

Element	Details
Scenario ID	GET_004
Scenario Name	Customer does not exist
HTTP Code	404
GIVEN	The user provides a customerId which does not exist
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 404 error
Example Error Message	`{"code": 1040, "message": "The entity of the following parameters [Company: EN, Customer: 213549674] was not found."}`

Sample Request

{
  "aliasName": "ShortName",
  "companyId": "EN",
  "countryCode": "GB",
  "customerGroupId": "1",
  "customerId": "",
  "customerName": "NewCustomerName",
  "externalReference": 123456,
  "invoice": {
    "calculatePayDiscountOnTax": true,
    "checkCreditOnHeadOffice": false,
    "creditLimit": 300000.0,
    "currencyCode": "GBP",
    "hasFixedCurrency": true,
    "hasFixedPaymentTerms": true,
    "hasFixedTaxSystem": false,
    "languageCode": "EN",
    "paymentTermsId": "30"
  },
  "payment": {
    "bankAccount": "123456789",
    "debtCollectionCode": "IK1",
    "payMethod": "IP",
    "postalAccount": "987654321",
    "status": "Active"
  },
  "contactPoints": [
    {
      "additionalContactInfo": {
        "contactPerson": "ContactName"
      },
      "address": {
        "countryCode": "GB",
        "place": "LONDON WC2R 3LT",
        "streetAddress": "2 Customer Address Street"
      },
      "contactPointType": "1",
      "phoneNumbers": {
        "telephone1": "+44 71 828939"
      }
    }
  ]
}

Note: This request does not contain a customerId and therefore relies on auto-numbering setup to automatically assign a new customerId.

Validation Rules for POST Method – Single

POST_001 - Autonumbering does not permit manual assignment

Element	Details
Scenario ID	POST_001
Scenario Name	Autonumbering does not permit manual assignment
HTTP Code	422
GIVEN	If there is an autonumbering series with manual assignment not permitted and the request body contains a customerId
WHEN	The API is called
BUT	—
THEN	The API stops with a 422 error which states that the Auto-numbering series is missing
Example Error Message	`{"code": 1010, "message": "Auto-numbering series is missing"}`

POST_002 - Autonumbering series cannot be established

Element	Details
Scenario ID	POST_002
Scenario Name	Autonumbering series cannot be established
HTTP Code	422
GIVEN	There are multiple autonumbering series available
WHEN	The API is called
BUT	—
THEN	The API stops with a 422 error which states that the Auto-numbering series is missing
Example Error Message	`{"code": 1010, "message": "Auto-numbering series is missing"}`

POST_003 - Autonumbering does not allow manual assignment

Element	Details
Scenario ID	POST_003
Scenario Name	Autonumbering does not allow manual assignment
HTTP Code	422
GIVEN	There is a single autonumbering series which does not permit providing a manual customerId and the request body contains a customerId
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 422 error which states that you may not manually provide a customer ID
Example Error Message	`{"code": 1010, "message": "You cannot enter a new ID manually (CustomerID)."}`

POST_004 - Missing mandatory fields

Element	Details
Scenario ID	POST_004
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	A user is authorised AND the JSON body is missing a field that is marked mandatory in the schema
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 422 error and a message
Example Error Message	`"The {0} field is required."`

POST_005 - Illegal value

Element	Details
Scenario ID	POST_005
Scenario Name	Illegal value
HTTP Code	422
GIVEN	A user is authorised AND the JSON body contains all mandatory properties AND one or more of the properties contain a value that is not permitted (for example, restricted to a list of attribute values)
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 422 error and a message
Example Error Message	`"countryCode": [{"code": 3010, "message": "Illegal value."}]`

POST_006 - Invalid format of fields

Element	Details
Scenario ID	POST_006
Scenario Name	Invalid format of fields
HTTP Code	400
GIVEN	A user is authorised AND the JSON body contains all mandatory properties AND one or more of the properties contain a value that does not meet the requirements of the data type defined in the schema
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 400 error and a message
Example Error Message	`{“code”: 1010, “message”: “The JSON value could not be converted to System.DateTime. Path: $.payment.expiryDate

POST_007 - Maximum string length is exceeded

Element	Details
Scenario ID	POST_007
Scenario Name	Maximum string length is exceeded
HTTP Code	422
GIVEN	A user is authorised AND the JSON body contains all mandatory properties AND one or more of the properties contain a value that exceeds the maximum length defined in the schema
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 400 error and a message
Example Error Message	`"The field {0} must be a string or array type with a maximum length of {1}."`

POST_008 - Duplicated customer

Element	Details
Scenario ID	POST_008
Scenario Name	Duplicated customer
HTTP Code	400
GIVEN	A user is authorised AND the JSON body contains all mandatory properties AND all the properties meet the schema requirements AND the customer ID provided already exists in the system
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 400 error and a message
Example Error Message	`"Your entry is not saved because meanwhile data has been changed by another user. Reload and try again."`

POST_009 - Invalid authorisation

Element	Details
Scenario ID	POST_009
Scenario Name	Invalid authorisation
HTTP Code	401
GIVEN	The token provided does not pass authorisation
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 401 error and a message
Example Error Message	`{"statusCode": 401, "message": "Invalid JWT."}`

POST_010 - User is not authorised to access API

Element	Details
Scenario ID	POST_010
Scenario Name	User is not authorised to access API
HTTP Code	403
GIVEN	The user is not authorised to access the API
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 403 error and a message
Example Error Message	`{"code": 2030, "message": "User is not authorized"}`

POST_011 - Missing general address

Element	Details
Scenario ID	POST_011
Scenario Name	Missing general address
HTTP Code	400
GIVEN	A user is authorised AND the JSON body does not contain at least one contactPoint of the “General” type
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 400 error and a message
Example Error Message	`{"code": 3010, "message": "General address has to be entered"}`

POST_012 - Missing mandatory relation

Element	Details
Scenario ID	POST_012
Scenario Name	Missing mandatory relation
HTTP Code	422
GIVEN	A user is authorised AND the JSON body does not contain a relation that is mandatory
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 422 error and a message
Example Error Message	`{"code": 3010, "message": "Relation for attribute LEGALID is mandatory."}`

POST_013 - Missing mandatory flexi-field values

Element	Details
Scenario ID	POST_013
Scenario Name	Missing mandatory flexi-field values
HTTP Code	422
GIVEN	A user is authorised AND the JSON body does not contain a flexi-field value that is set as mandatory in the flexi-field group definition
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 422 error and a message
Example Error Message	`"customFieldGroups": {"Test_value": {"n2_fx": "", "notificationMessages": {"n2_fx": [{"code": 3010, "message": "Please enter a value"}]}}}`

POST_014 - Flexi-field value is not valid

Element	Details
Scenario ID	POST_014
Scenario Name	Flexi-field value is not valid
HTTP Code	422
GIVEN	A user is authorised AND the JSON body contains a flexi-field value that is not permitted according to the flexi-field group definition
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 422 error and a message
Example Error Message	`{"code": 3010, "message": "The value entered is not valid according to the restrictions for this field."}`

POST_015 - Invalid JSON structure

Element	Details
Scenario ID	POST_015
Scenario Name	Invalid JSON structure
HTTP Code	400
GIVEN	A user is authorised
WHEN	The PATCH request body is malformed
BUT	—
THEN	The API stops with a 400 error
Example Error Message	—

Sample Request

[
  {
    "path": "/payment/payMethod",
    "op": "Replace",
    "value": "SB"
  }
]

[
  {
  "path": "/contactPoints/-",
  "op": "Add",
  "value": { 
    "additionalContactInfo": {
      "contactPerson": "Add_Contact_1",
      "contactPosition": "Add_Position_1",
      "eMail": "Add_email_1@test.com",
      "eMailCc": "Add_emailcc_1@test.com",
      "gtin": "add_gtin_1",
      "url": "www.add_url_1_.com"
    },
    "address": {
      "countryCode": "GB",
      "place": "Add_Place_1",
      "postcode": "PST1",
      "province": "ADDPROV_1",
      "streetAddress": "add_street_address_1"
    },
    "contactPointType": "4",
    "phoneNumbers": {
      "telephone1": "+aaaaaa",
      "telephone2": "+bbbbbb",
      "telephone3": "+cccccc",
      "telephone4": "+dddddd",
      "telephone5": "+eeeeee",
      "telephone6": "+ffffff",
      "telephone7": "+gggggg"
      }
    }
  }
]

[
  {
  "path": "/contactPoints/1",
  "op": "Remove"
  }
]

[
  {
  "path": "/payment/payMethod",
  "op": "Replace",
  "value": "DD"
  },
  {
  "path": "invoice/currencyCode",
  "op": "Replace",
  "value": "NOK"
  },
  {
  "path": "/contactPoints/0/additionalContactInfo/contactPerson",
  "op": "Replace",
  "value": "Replaced_ContactPerson"
  },
  {
  "path": "/contactPoints/-",
  "op": "Add",
  "value": { 
    "additionalContactInfo": {
      "contactPerson": "Add_Contact_2",
      "contactPosition": "Add_Position_2",
      "eMail": "Add_email_1@test.com",
      "eMailCc": "Add_emailcc_2@test.com",
      "gtin": "add_gtin_2",
      "url": "www.add_url_2_.com"
    },
    "address": {
      "countryCode": "GB",
      "place": "Add_Place_2",
      "postcode": "PST2",
      "province": "ADDPROV_2",
      "streetAddress": "add_street_address_2"
    },
    "contactPointType": "4",
    "phoneNumbers": {
      "telephone1": "+aaaaaa",
      "telephone2": "+bbbbbb",
      "telephone3": "+cccccc",
      "telephone4": "+dddddd",
      "telephone5": "+eeeeee",
      "telephone6": "+ffffff",
      "telephone7": "+gggggg"
    }
  }
}
]

Limits & Notes

One customer per call.
Multiple patch operations may be made in a single request for that customer.
Patch operators available: Replace, Add, Remove
Supported operations: Update payment method, currency, contact information, addresses

Validation Rules for PATCH Method – customerId

PATCH_001 - Invalid authorisation

Element	Details
Scenario ID	PATCH_001
Scenario Name	Invalid authorisation
HTTP Code	401
GIVEN	The token provided does not pass authorisation
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 401 error and a message
Example Error Message	`{"statusCode": 401, "message": "Invalid JWT."}`

PATCH_002 - User is not authorised

Element	Details
Scenario ID	PATCH_002
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	A user is not authorised
WHEN	The PATCH request is sent
BUT	—
THEN	The API stops with a 403 error
Example Error Message	`{"code": 2030, "message": "User is not authorized"}`

PATCH_003 - Invalid customerId

Element	Details
Scenario ID	PATCH_003
Scenario Name	Invalid customerId
HTTP Code	404
GIVEN	A user is authorised
WHEN	The PATCH request is sent to a non-existent customerId
BUT	—
THEN	The API stops with a 404 error
Example Error Message	`{"code": 1040, "message": "Customer with Id 11000999 was not found within company EN"}`

PATCH_004 - Invalid JSON structure

Element	Details
Scenario ID	PATCH_004
Scenario Name	Invalid JSON structure
HTTP Code	400
GIVEN	A user is authorised
WHEN	The PATCH request body is malformed
BUT	—
THEN	The API stops with a 400 error
Example Error Message	—

PATCH_005 - Invalid path

Element	Details
Scenario ID	PATCH_005
Scenario Name	Invalid path
HTTP Code	400
GIVEN	A user is authorised
WHEN	The PATCH request contains a path that is not supported
BUT	—
THEN	The API stops with a 400 error and returns a message (content depends on the way the path is malformed)
Example Error Message	`{"code": 4020, "message": "PatchOperation index 0: Provided path \"/customFieldroups/mfa/name\" is invalid"}` / `{"code": 4023, "message": "PatchOperation index 0: Provided index (0) is out of range"}` / `{"code": 4020, "message": "PatchOperation index 0: _Path does not specify object member"}`

PATCH_006 - Illegal value

Element	Details
Scenario ID	PATCH_006
Scenario Name	Illegal value
HTTP Code	422
GIVEN	A user is authorised
WHEN	The PATCH request contains a valid path
BUT	One or more values are not permitted
THEN	The API stops with a 422 error
Example Error Message	`{"code": 3010, "message": "Invalid payment method"}`

PATCH_007 - Invalid format

Element	Details
Scenario ID	PATCH_007
Scenario Name	Invalid format
HTTP Code	400
GIVEN	A user is authorised
WHEN	The PATCH request contains a valid path
BUT	One or more values do not meet the format requirements
THEN	The API stops with a 400 error
Example Error Message	`{"code": 4030, "message": "PatchOperation index 0: Unable to convert value {0} to type 'System.Double' as an input value for the property {1}"}`

PATCH_008 - Maximum string length is exceeded

Element	Details
Scenario ID	PATCH_008
Scenario Name	Maximum string length is exceeded
HTTP Code	422
GIVEN	A user is authorised AND the JSON body contains all mandatory properties AND one or more of the properties contain a value that exceeds the maximum length defined in the schema
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 400 error and a message
Example Error Message	`"The field {0} must be a string or array type with a maximum length of {1}."`

PATCH_009 - Illegal operation value

Element	Details
Scenario ID	PATCH_009
Scenario Name	Illegal operation value
HTTP Code	400
GIVEN	The patch operation is not supported
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 400 error and a message
Example Error Message	`“The JSON value could not be converted to U4.PublicApiFramework.Core.JsonPatch.OperationType. Path: $[0].op

Sample Request

DELETE /v1/customers/11000002?companyId=EN

Limits & Notes

Only a single customer can be updated.
This endpoint does not delete the customer, but alters the status to “Closed”.
The operation may be undone with a Replace operation through the PATCH endpoint on the path “/payment/status”.
To fully delete the customer, you need to use the deletion routine “Delete customers and suppliers” available in the system administration menu.

Validation Rules for DELETE Method

DEL_001 - Invalid authorisation

Element	Details
Scenario ID	DEL_001
Scenario Name	Invalid authorisation
HTTP Code	401
GIVEN	The token provided does not pass authorisation
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 401 error and a message
Example Error Message or Response	`{"statusCode": 401, "message": "Invalid JWT."}`

DEL_002 - User is not authorised to access API

Element	Details
Scenario ID	DEL_002
Scenario Name	User is not authorised to access API
HTTP Code	403
GIVEN	The user is not authorised to access the API
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 403 error and a message
Example Error Message or Response	`{"code": 2030, "message": "User is not authorized"}`

DEL_003 - Customer does not exist

Element	Details
Scenario ID	DEL_003
Scenario Name	Customer does not exist
HTTP Code	404
GIVEN	The user provides a customerId which does not exist
WHEN	The API request is sent
BUT	—
THEN	The API stops with a 404 error and a message
Example Error Message or Response	`{"code": 1040, "message": "The entity of the following parameters [Company: EN, Customer: 213549674] was not found."}`

Best Practices

The customers object API schema may differ from the POST/PATCH schema. Therefore, it is recommended to use the GET endpoint instead.
The DELETE endpoint does not physically delete customers but updates the status of the record. To ensure proper deletion, the deletion routine should be executed.
The customers API is designed for single-customer operations only. For batch functionality, refer to the Import Customers and Suppliers process.
Ensure integrations properly manage PATCH operations - always verify target values before and after the operation.
Use Swagger UI for testing and schema validation before production calls.
Handle error codes gracefully - implement retry/backoff logic in line with global rate limits.
Always check for deprecation alerts on the endpoint version in use.

ERPx

ERPx

U4 ERPx

Customers

The Customers API in Unit4 ERPx manages customer-related data such as creation, retrieval, updates, and termination (soft-delete) of customer 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 GET Method – Single

Sample Request

Validation Rules for POST Method – Single

Sample Request

Limits & Notes

Validation Rules for PATCH Method – customerId

Sample Request

Limits & Notes

Validation Rules for DELETE Method

Best Practices

Action APIs

Query APIs (Read-Only)

U4 ERPx

Customers

The Customers API in Unit4 ERPx manages customer-related data such as creation, retrieval, updates, and termination (soft-delete) of customer 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 GET Method – Single

Sample Request

Validation Rules for POST Method – Single

Sample Request

Limits & Notes

Validation Rules for PATCH Method – customerId

Sample Request

Limits & Notes

Validation Rules for DELETE Method

Best Practices

Related endpoints

Action APIs

Suppliers

Customer Transactions

Query APIs (Read-Only)

Customers Object API

Customer Groups

Customer Payment Recipients

Customer Remittances

Customer Remittance Payments

Customers and Suppliers

Customer Transactions Object

Import Customers or Suppliers

Matched Customer Transactions

Open Customer and Supplier Transactions

Customer Invoices