Glossary
A comprehensive reference of key terms and concepts.
1. Getting Started
Federated Identity Provider: A service that allows users to log in using credentials from another trusted system, supporting single sign-on and secure authentication across platforms.
HTTP Methods (GET, POST, PUT, DELETE): Standard operations used in RESTful APIs to interact with resources. GET retrieves data; POST creates new data; PUT updates existing data; DELETE removes data.
JSON (JavaScript Object Notation): A lightweight, machine-readable data format commonly used for exchanging information between APIs and applications.
OAuth 2.0: An industry-standard protocol for authorisation, allowing secure access to resources without sharing passwords. Used by ERPx APIs for secure authentication.
Read-only Endpoint: An API endpoint that allows data to be viewed but not modified. For example, GET /employees returns employee data without making changes.
U4IDS (Unit4 Identity Services): The identity management system used to authenticate and authorise users for ERPx and its APIs.
Versioned Endpoints: API endpoints that include version numbers (e.g., /v1/) to maintain compatibility and stability as the platform evolves.
2. Auth and Security
Business Use Case: A real-world application scenario demonstrating how an API or system solves a particular business problem.
Credentials: Information (such as usernames, passwords, or keys) required to authenticate and authorise access to systems or applications.
HTTPS: Hypertext Transfer Protocol Secure; an encrypted communication protocol for secure data transfer over the internet.
Tenant Isolation: Ensuring that data and access for one tenant (organisation or user group) are strictly separated from others in a shared environment.
Token: A digital key or credential used to authenticate a user or application to an API, typically with a limited validity period.
Token Expiration: The duration for which a token remains valid before it must be refreshed or replaced.
Token Refresh: The process of renewing an expired or soon-to-expire token to maintain uninterrupted access to an API.
3. Limits and Quotas
Amendment Logging API: An API for logging changes or events within the system.
API Call Timeout: The maximum duration allowed for an API call before it is terminated.
API Requests (Tenant-Level): The total number of API requests permitted for a tenant within a specified period.
Batch APIs: APIs designed for processing large datasets in batches.
Common Limit-Related Response Codes: Standard HTTP response codes indicating issues related to limits, such as payload too large, too many requests, or service unavailable.
Daily Data Transfer: The combined total of inbound and outbound data transfer allowed within a 24-hour period.
Exponential Backoff with Jitter: A retry strategy where the delay between retries increases exponentially, with a random component added to avoid synchronised retries.
Inbound Data Transfer: The amount of data that can be transferred into the system within a set time frame.
Maximum API Call Size: The largest payload size permitted for a single API call, excluding file upload/download and batch uploads.
Maximum Document Archive File Size: The largest file size allowed for document storage and retrieval.
Maximum Field Character Length: The maximum number of characters permitted in a standard field.
Maximum Machine-to-Machine Clients: The maximum number of authentication clients allowed per tenant.
Maximum Records per API Call: The highest number of records that can be retrieved in a single API call.
Objects APIs: APIs used for displaying, aggregating, and retrieving large sets of data.
Outbound Data Transfer: The amount of data that can be transferred out of the system within a set time frame.
Reporting APIs: APIs used for generating system reports.
Sliding Window Rate Limiting Algorithm: A method of rate limiting that distributes request capacity evenly and allows for natural bursts while preventing starvation at window boundaries.
4. Financial Transaction Batch API
Batch: A group of financial transactions processed together.
batchId: Unique identifier for a batch of transactions.
currencyAmount: The amount of money in a specified currency.
GL: General Ledger; a main accounting record.
Interface: The integration interface identifier for the batch.
Period: Accounting period for the transaction (e.g., 202301 for January 2023).
sequenceNumber: The order of a transaction line within a batch.
taxCode: Code representing the tax applied to a transaction.
transactionDetailInformation: Detailed information about each transaction line, including account and amount.
transactionType: Type of transaction (e.g., ‘A1’).
5. Employees API
Autonumbering (RESNO): A feature that automatically assigns a unique personId if not provided during employee creation.
childStrategy: A parameter used when updating employments and their relations, specifying how child entities should be handled (e.g., “AddOrUpdate”, “Update”, “UpdateValidAsOfStartDate”).
contactPoints: A list of contact details for an employee, such as addresses and types.
contactPointType: Specifies the type of contact point (e.g., address, phone).
payMethod: Indicates the method of payment for the employee (e.g., “CH” for cheque).
personId: A unique identifier for each employee within a company.
personnelType: Specifies the type of personnel (e.g., “E” for employee).
relatedValues: Additional data points related to the employee, such as relationships or attributes.
status: Indicates the current status of the employee (e.g., “N” for new, “Terminate” for terminated).
supplierGroupId / supplierId: Identifiers related to the supplier group and supplier for payment processing.
Workflow: A process that may require approval for certain fields when creating or updating an employee. If active, the API response will indicate which fields are pending approval.
6. Projects API
Activities: Actions or tasks associated with a project.
Billing Information: Details related to the financial aspects of a project, such as invoices and price lists.
Error Codes: Standard HTTP codes returned by the API to indicate the result of a request (e.g., 200 for success, 403 for forbidden, 422 for unprocessable entity, 404 for not found).
Global Projects: Projects that span multiple companies or regions within the system.
Microservices: A software architecture style where applications are composed of small, independent services that communicate over APIs.
Portfolio: A collection of projects managed by the currently logged-in user as Project Manager.
Project Manager: The user assigned to oversee and manage a project.
ProjectId: A unique identifier for a project within a company.
Status: The current state of a project, such as ‘Active’, ‘Closed’, or ‘Terminated’.
Work Orders: Tasks or assignments associated with a project, managed through related API endpoints.
7. Customers API
Batch Import: The process of adding multiple resources at once.
Error Code: A numeric or textual indicator of a problem encountered during an API operation.
Method: The type of operation performed by an API, such as retrieving, creating, updating, or deleting data.
Object API: An endpoint that returns structured data about resources.
Operation: An action performed on a resource, such as add, replace, or remove.
Request Body: The data sent to an API endpoint to perform an operation.
Response: The data returned by the API after processing a request.
Status: The current state of a resource, such as active or closed.
8. Webhooks and Events
Correlation ID: An identifier linking related events across systems.
Dead Letter Queue: A mechanism for storing events that fail after all retries.
Document Event: An event representing changes to business entities within the ERP system.
Event: A notification broadcast by the ERP system when a significant action occurs.
Event Filter: Criteria defining which events trigger a webhook.
Event Header: Standardised metadata included with each event.
Event Naming: The hierarchical convention used to identify events.
Event Payload: The JSON structure containing event data.
Event Subscription: Configuration specifying which events an application wants to receive.
Event Versioning: The practice of assigning version numbers to events for compatibility.
Idempotency: The property of processing events safely even if delivered multiple times.
Message Event: An event representing system-level or process-oriented occurrences.
Metadata Address: A service that augments webhook requests with additional context.
Mutual TLS (mTLS): A security protocol using client certificates for authentication.
Primary Response: The HTTP status code returned by a webhook endpoint.
Retry Policy: The configuration for handling delivery failures.
Secondary Response: Optional data returned to be used in downstream processes.
Templating System: A feature for transforming event payloads before delivery.
Webhook Endpoint: An HTTP endpoint that receives and processes event notifications.
Wildcard: A symbol used in event subscriptions for flexible filtering.
9. Work Orders API
Autonumbering: The automatic assignment of a unique identifier to a new work order.
CustomerInformation: Data related to the customer associated with a work order.
InvoiceSeparately: A field indicating if the invoice should be issued separately.
InvoiceStatus: A field indicating whether a work order is billable.
ProjectManagerId: An identifier for the manager of a project.
Reference: The name of the contact person for the customer.
RelatedValues: Additional values or attributes associated with a work order.
ServiceOrder: A field indicating whether a work order is assigned as a service order.
Status: The current state of a work order, such as ‘New’ or ‘Closed’.
Swagger UI: A user interface for testing and validating API endpoints and schemas.
Work Order: A record related to a project that can be created, retrieved, updated, or closed.
10. Attribute Relations API
Attribute Relations: Connections between attributes that define how they are related within the system.
AttributeId: Identifier for a specific attribute.
AttributeName: Name of the attribute.
AttributeValue: The value assigned to an attribute.
Best Practices: Recommended approaches for using the API effectively and safely.
Error Message: Information returned when an operation fails, describing the issue.
RelatedAttributeId: Identifier for the attribute that is related to another attribute.
RelatedAttributeName: Name of the attribute that is related to another attribute.
RelationDateFrom: The start date for the validity of the attribute relation.
RelationDateTo: The end date for the validity of the attribute relation.
RelationValue: The value that links the related attribute.
RelationValueStatus: Status indicating the state of the relation value.
11. Attribute Values API
Attribute: A property or characteristic that can be assigned a value within the system.
Company ID: An identifier representing a company within the system.
Contact Information: Details that allow communication with a person or entity.
Custom Value: A user-defined value for an attribute.
Description: A brief explanation or summary of an attribute or value.
Filter: A condition used to limit the results returned by a query.
Header: Metadata included in an API request or response.
OData: A protocol for querying and updating data using standard syntax.
Offset: The number of items to skip before returning results in a query.
Order By: A specification for sorting query results.
Owner: The entity responsible for a particular attribute value.
Patch Document: A set of instructions describing changes to be made to an attribute value.
Period: The time span during which an attribute value is valid.
Relation: A connection between two attributes or attribute values.
Status: The current state of an attribute value, such as active or closed.
12. Versioning and Deprecation
API Versioning: Assigning version numbers to API endpoints (such as /v1/, /v2/) to manage changes and ensure stability for existing integrations.
Backward Compatibility: The ability of the API to accept extra properties in requests (which it ignores) and to add new optional properties in responses (which clients should handle gracefully).
Breaking Change: A modification to the API that requires a new version because it could disrupt existing integrations. Examples include changes to object structure, required headers, removal of properties, changes to resource meaning or data types, and new HTTP status codes.
Discovery Endpoint: A special API endpoint (such as /v1/discovery/apis) that allows clients to check available API versions and their status (Current, Deprecated, etc.).
HTTP Status Codes: Standardised codes returned by the API to indicate the result of a request (for example, 2xx for success, 4xx for client errors, 5xx for server errors, 410 Gone for removed endpoints).
Migration: The process of updating integrations to use a newer API version, typically involving reviewing release notes, testing, and incremental updates.
Non-Breaking Change: A change that does not require a new version, as it does not disrupt existing integrations. Examples include adding optional properties, query parameters, headers, or new optional endpoints.
Release Notes: Documentation detailing changes, especially breaking changes, between API versions to assist with migration.
Sunset: The final stage of deprecation, when the deprecated API version is removed and all requests to it return a 410 Gone status.
Swagger Specification: A documentation format (often a JSON or YAML file) that describes the API, including deprecation notices.
X-U4-Warning Header: A response header indicating that an endpoint is deprecated and scheduled for removal.
13. Landing Page
Authorisation: Granting access rights to users or systems. Token-based authorisation is highlighted as a security measure for ERPx APIs.
Credential Storage: The secure management and storage of authentication credentials (such as API keys or tokens) to protect sensitive data.
Developer Portal: A centralised hub for accessing ERPx API documentation, integration guides, and platform standards. It is designed to help developers onboard quickly and integrate efficiently.
Event-Driven Integration: A system design where integrations respond to real-time events (such as data changes) rather than periodic polling. ERPx supports this via Message Hub and webhooks.
Integration: The process of connecting different systems or applications to work together, often using APIs.
Token-Based Authorisation: A security mechanism where access to APIs is granted via tokens, which are issued after successful authentication.
Versioning: The practice of managing changes to APIs by assigning version numbers (e.g., /v1/, /v2/). This ensures stability and backward compatibility.
14. Error Handling
200 OK: The request was completed successfully. Indicates a standard successful response for HTTP requests.
201 Created: A new resource was successfully created, typically in response to a POST request.
202 Accepted: The request has been accepted for processing, but the processing is not complete.
204 No Content: The request was successful, but there is no content to return in the response.
400 Bad Request: The request contains invalid syntax or is malformed. Review the request’s syntax and parameters.
401 Unauthorised: Authentication is missing or invalid. Verify API credentials.
403 Forbidden: The user is authenticated but does not have permission to access the resource. Check user access rights.
404 Not Found: The resource or endpoint does not exist. Verify the URI and resource ID.
405 Method Not Allowed: The HTTP method used is not supported for the endpoint. Use the correct HTTP method (GET, POST, etc.).
409 Conflict: A concurrency or duplicate resource error occurred. Retrieve the latest version of the resource and retry the update.
413 Payload Too Large: The request’s data is too large. Refer to limits and quotas documentation.
422 Unprocessable Entity: Business logic or validation failed. Parse the notificationMessages object for details, correct invalid values, and resubmit the request.
429 Too Many Requests: Rate limit exceeded. Implement backoff and retry logic.
500 Internal Server Error: An unexpected server-side error occurred. Retry the request and contact support if the issue persists.
503 Service Unavailable: The service is temporarily unavailable. Implement retry logic with exponential backoff.
Concurrency Error (Error Code: 3090): Occurs when another user modifies or deletes a resource after it was retrieved but before it was updated.
Duplicate Resource Error (Error Code: 3090): Occurs when attempting to create a resource that already exists with the same unique identifiers.
Exponential Backoff: A retry strategy where the wait time between retries increases exponentially, used for handling rate limits and temporary server errors.
Invalid Endpoint (Error Code: 1030): The API endpoint URI does not exist.
Model Validation Error (Error Code: 3010): Indicates a validation error in the request model.
notificationMessages Object: A part of the error response that contains detailed validation errors for each field.
Resource Not Found (Error Code: 1040): The endpoint is valid, but the specific resource ID does not exist.
15. Document Archives API
DocType: The type or category of a document (e.g., PERSONNEL).
Document Archive: A system or repository for storing, retrieving, and managing documents.
ExpiryDate: The date after which a document is considered expired.
ID: A unique identifier for a document, usually in GUID format.
Indexes: Additional metadata fields used to categorise or filter documents.
Start: The zero-based offset indicating where to begin returning results in a paginated response.
Status: The current state of a document (e.g., “N” for new, “T” for deleted).
16. Document Archive Revisions API
Document Revision: A specific version of a document stored in the archive. Each revision is identified by a revision number and can be retrieved or created via the API.
HTTP Code: A standard response code returned by the API to indicate the result of a request (e.g., 200 for success, 400 for bad request, 403 for forbidden, 404 for not found).
Pagination Envelope: A structure in the API response that includes metadata such as start, limit, count, total, and the items array for paginated results.
17. Objects API
Attribute: A key concept in Unit4 ERPx, representing a property that can be filtered using values from the attribute-values endpoint.
Common parameters: Options used in API requests to control the data returned. Common parameters include select, filter, orderBy, limit, offset, companyId.
Custom Annotations: Metadata extensions in the response model that provide additional capabilities or information, such as x-u4-key, x-u4-filterable, x-u4-describable, x-u4-valueList, x-u4-attribute, x-u4-relation, x-u4-complextype.
Data Consistency: Ensuring reliable data extraction during pagination or incremental loading, with strategies to compensate for ongoing updates.
Enterprise Documents: Core business entities in Unit4 ERPx, returned as structured JSON objects with properties grouped by business function. Governed by an ontology for consistent property naming.
Horizontal Filtering: The practice of restricting the list of returned documents using the filter parameter.
Incremental Load: Loading only data changed since the last cycle, using the lastUpdated property for efficient data retrieval.
ObjectAPI: The API endpoints in Unit4 ERPx that provide structured access to Enterprise Documents, enabling integrations and data queries across business entities.
Related Values: Additional values attached to Enterprise Documents, accessible via the relatedValues property. Types include RelatedValueOfAttributes, RelatedValueOfProduct, RelatedValueOfResource, and RelatedValueOfAsset.
Response Headers: Custom headers in API responses providing additional information, such as X-U4-RemainingLimit, X-U4-QuotaType, and Retry-After.
Response Model: The schema describing the structure of an Enterprise Document, including properties, property groups, and associations. Determines what can be used in select, filter, and orderBy.
Sorting: Ordering returned documents using the orderBy parameter, referencing properties directly or via nested paths.
Value List: A backend-defined list of possible values for a property, retrievable via the value-list endpoint. Used for filtering properties with controlled values.
Vertical Sectioning: The practice of retrieving only required properties from Enterprise Documents using the select parameter.
18. Use Cases
Account Manager: A CRM user responsible for managing customer relationships and overseeing financial profiles, balances, and payment behaviour.
AR (Accounts Receivable): The outstanding invoices or money owed by customers to a company, tracked and synchronised between ERPx and CRM.
CRM (Customer Relationship Management): A system (such as Microsoft Dynamics 365) used to manage interactions with customers, including financial data and sales opportunities.
Customer Balance Report: A report generated via ERPx APIs that provides details on customer balances, payment profiles, and financial status.
Customer Master Data: Core customer information (identification, address, reference data) maintained consistently across ERPx and CRM.
D-U-N-S Number: A unique identifier for businesses, used for cross-referencing customer records between CRM and ERPx.
E-sign Platform: A digital service (such as DocuSign) integrated with ERPx to automate electronic signing of employee documents.
Exchange Rate Provider: A bank or service (e.g., Norges Bank) supplying currency exchange rates for multi-currency transactions in ERPx.
Integration/Extension Toolkit (EIT): A middleware component facilitating data synchronisation and workflow automation between ERPx and other systems.
Opportunity Project: A project in ERPx created from a qualified CRM opportunity, capturing pre-sales efforts and resource planning.
Purchase Order (PO): An official document issued by a buyer to a supplier, automated for transmission from ERPx to external marketplaces.
SRM (Supplier Relationship Management): A system for managing supplier records, onboarding, and e-invoice processing, synchronised with ERPx.
Supplier Group: A classification of suppliers in ERPx, used to determine eligibility for synchronisation with SRM.
VAT (Value Added Tax): A tax on goods and services, with supplier VAT numbers validated against the EU VIES database for compliance.
VIES (VAT Information Exchange System): An EU system for validating supplier VAT registration numbers to ensure legal compliance.
XML (eXtensible Markup Language): A file format used for automated VAT statement generation and archiving in ERPx.
General Glossary
API (Application Programming Interface): A set of rules and protocols that enables different software systems to communicate with each other. In ERPx, APIs provide a safe, consistent, and documented way to access data and functions without direct interaction with the database or internal logic.
Authentication: The process of verifying the identity of a user or system. ERPx APIs use secure authentication methods such as OAuth 2.0 and support federated identity providers to ensure only authorised access.
Base URL: The root address used to access the API endpoints.
Client ID: An identifier used to authenticate an application accessing the API.
Client Secret: A confidential key used alongside the Client ID for authentication.
CompanyId: A parameter representing the unique identifier for a company. It is required for many API operations to ensure the correct company’s documents are accessed.
Contact Points: Address and contact information attached to Enterprise Documents, returned under the contactPoints property.
CRUD Operations: An acronym for Create, Read, Update, and Delete. These are the four basic functions of persistent storage and are supported by the API for managing document revisions.
Custom Fields (Flexi-fields): Dynamically attached fields to master files, discoverable via schema requests or specific endpoints.
Deprecation: The process of phasing out an API version. It involves communication to users, a grace period for migration, and eventual removal (sunset) of the deprecated version.
Deprecation Alert: A notification indicating that an API version or endpoint is outdated or will be removed.
DTO (Data Transfer Object): An object used to transfer data between processes.
Endpoint: A specific URL or URI at which an API can be accessed to perform a specific function or retrieve data.
ERPx (Enterprise Resource Planning Extension): A platform for managing business processes, including finance, procurement, HR, and integration with external systems.
FileContent: The actual content of a document or revision, typically encoded in Base64 format for transmission via the API.
FileName: The name of the file associated with a document revision. It must include a valid file extension.
Grace Period: A transitional period after an API is deprecated but before it is fully removed (sunset), allowing developers time to migrate.
GUID (Globally Unique Identifier): A 128-bit identifier used to uniquely identify documents and revisions within the system.
Limit: The maximum number of items returned in a single API response.
Message Hub: A component of ERPx that delivers real-time events to subscribed integrations, enabling event-driven workflows.
MimeType: A string indicating the media type of the file (e.g., image/jpeg, application/pdf). It must match the file’s actual content.
Pagination: A technique for retrieving large datasets in chunks using limit and offset parameters, or optimised strategies using key values.
Payload: The data or information sent in an API request or response.
Rate Limits: Restrictions on how many API requests can be made within a certain period, designed to protect system performance and prevent abuse.
RevisionNo: The number assigned to a specific revision of a document. Used to retrieve or reference a particular version.
Soft-delete: The process of marking a record, project, or document as terminated rather than permanently remove it from the system.
Swagger Schema: A specification that describes the structure and validation rules of API requests and responses.
System Parameters: Configuration settings related to project management, referenced in the API documentation.
Tenant: A dedicated instance of ERPx assigned to a specific organisation or customer, ensuring data separation and security.
Thumbnail: A small image representation of a document or revision, retrievable via a dedicated API endpoint.
Validation Rules (BDD): Business-driven development rules that define scenarios for API responses, including error handling for missing fields, invalid formats, permissions, and duplicate entries.
Webhook: A mechanism that allows one system to send real-time data to another system as soon as an event occurs, commonly used for event-driven integrations.