Supplier CIS Details

The Supplier CIS Details API in Unit4 ERPx manages CIS (Construction Industry Scheme) details for suppliers, including business type, verification records, and tax treatment. It supports creating and updating CIS records via a single PATCH endpoint.

Purpose:
This API is used to create and update CIS (Construction Industry Scheme) details for suppliers registered in Unit4 ERPx. The CIS is a UK tax scheme that applies to contractors and subcontractors in the construction industry.

Base URL:
/v1/supplier-cis-details

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 → System and common parameters → System parameters and values → System parameters → Common and System administration → Financials → Accounts Payable (SU, CS).
The following system parameters must be active and configured: CIS_GROSS_RATE, CIS_NET_RATE, CIS_UNMATCHED_RATE, CIS_TAX_SYSTEM_1.    

Supported Methods

Swagger / Schema

Version v1

Version v1

Method Details

• GET Method (Supplier CIS Details Object API)
• PATCH Method

GET https://eu01.erpx-api.unit4rd.com/v1/objects/supplier-cisdetails

[
  {
    "path": "/businessType",
    "op": "Replace",
    "value": "soletrader"
  },
  {
    "path": "/utr",
    "op": "Replace",
    "value": "1234567890"
  },
  {
    "path": "/niNumber",
    "op": "Replace",
    "value": "AB123456C"
  },
  {
    "path": "/firstName",
    "op": "Replace",
    "value": "John"
  },
  {
    "path": "/surname",
    "op": "Replace",
    "value": "Smith"
  },
  {
    "path": "/contract",
    "op": "Replace",
    "value": true
  },
  {
    "path": "/employmentStatusCheck",
    "op": "Replace",
    "value": true
  }
]
  

[
  {
    "path": "/businessType",
    "op": "Replace",
    "value": "partnership"
  },
  {
    "path": "/utr",
    "op": "Replace",
    "value": "1234567890"
  },
  {
    "path": "/niNumber",
    "op": "Replace",
    "value": "AB123456C"
  },
  {
    "path": "/partnershipName",
    "op": "Replace",
    "value": "Smith & Sons"
  },
  {
    "path": "/partnershipUtr",
    "op": "Replace",
    "value": "9876543210"
  },
  {
    "path": "/tradingName",
    "op": "Replace",
    "value": "Smith Construction"
  },
  {
    "path": "/contract",
    "op": "Replace",
    "value": true
  },
  {
    "path": "/employmentStatusCheck",
    "op": "Replace",
    "value": true
  }
]
  

[
  {
    "path": "/verifications/0/matchStatus",
    "op": "Replace",
    "value": "Matched",
    "supportNestedCollections": true
  },
  {
    "path": "/verifications/0/verificationNo",
    "op": "Replace",
    "value": "V1234567890",
    "supportNestedCollections": true
  },
  {
    "path": "/verifications/0/taxTreatment",
    "op": "Replace",
    "value": "Net",
    "supportNestedCollections": true
  }
]
  

[
  {
    "path": "/businessType",
    "op": "Replace",
    "value": "company"
  },
  {
    "path": "/utr",
    "op": "Replace",
    "value": "1234567890"
  },
  {
    "path": "/companyRegistrationNumber",
    "op": "Replace",
    "value": "AB123456"
  },
  {
    "path": "/tradingName",
    "op": "Replace",
    "value": "Acme Construction Ltd"
  },
  {
    "path": "/contract",
    "op": "Replace",
    "value": true
  },
  {
    "path": "/employmentStatusCheck",
    "op": "Replace",
    "value": true
  }
]
  

Best Practices

• Understand business type requirements before patching — each business type (soletrader, partnership, company, trust) has different mandatory fields. Review the mandatory fields table above to ensure your request includes all required data.
• Business type transitions clear fields automatically — when changing business type, fields that are no longer applicable are cleared by the API regardless of what values you send. Plan your integration accordingly.
• Verification records are timeline-managed — the API automatically sets dateTo on previous verifications and defaults dateFrom to today when omitted. Do not attempt to manually manage these fields.
• The taxRate field is read-only — it is automatically determined from system parameters based on the taxTreatment value. Do not include it in patch operations.
• Use uppercase for niNumber and companyRegistrationNumber — the API validates that these fields contain only uppercase letters.
• Ensure system parameters are configured — the four CIS system parameters must be active before using this API.
• 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.    

Related endpoints

Action APIs

Query APIs (Read-Only)