Onix API - Get started

Knowledge base
,
1

Overview

Onix API has a Swagger interface, which offers developers a quick view of all available APIs. Developers can use Swagger interface to test, and we recommend developers to test on the Sandbox environment.

Production environment:

Sandbox environment:

Data exchange format: JSON.

Secured by: Token-based authentication.

API requests and responses

Requests

Onix API uses JSON format to communicate. All available public APIs can be found on our Swagger page.

Action Field value Comment
Create null Follow the endpoint notes for the field. Otherwise, Onix API uses the field’s default value.
Update null Follow the endpoint notes for the field. Otherwise, Onix API ignores the field and leaves its data unchanged.
""
(empty string)		 Clears a string field when the field permits an empty string.

Success responses

Successful responses return 200 OK with JSON-formatted data. Common response types include:

  • An integer.
  • A boolean.
  • A single string.
  • Key-value pair list – key and value types are both string type.

Note: Parsing may be needed when using them in different types for specific endpoints.

Error responses

Status code Description
400 Bad request.
Please check your request’s parameters and body. See examples of bad request’s response below this table.
401 Unauthorized request.
Please check if you are:
• Missing a token.
• Missing or using incorrect scheme: Bearer for short-lived token, Key for long-lived token.
500 System errors.
If you encounter any issues or have questions, contact Onix Support for assistance.

Examples of 400 Bad Request responses:

  • Validation error response: Request field contains incorrect format or invalid values.
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-301ec3c5a9ce095960f403c21865b69d-7a1a2d1c823e7f70-00",
  "errors": {
    "source": [
      "Source is invalid"
    ],
    "erpOrderDate": [
      "ErpOrderDate wrong format"
    ]
  }
}
  • Logic/state error response:
[
  {
    "memberNames": [
      "workflowStatusId"
    ],
    "errorMessage": "Invalid Workflow Status Id"
  }
]

Authentication

Onix API uses token-based authentication. There are two types: short-lived tokens and long-lived tokens.

  • Long-lived token: The most commonly used method for Onix API integrations. It is associated with your company and uses the Key scheme.
  • Short-lived token: Acquired using your Onix Work account credentials. It expires after 60 minutes and uses the Bearer scheme.

Acquire and use the long-lived token

To create a long-lived token:

  1. Sign in to Onix Work in the environment you want to use.
  2. Go to Settings > External data-sources > API configuration.
  3. Select New.
  4. Enter the token’s expiry date and select Save.

The complete token is shown only once immediately after creation. Store it securely; you can copy the token again later from API configuration, but it is not displayed in full.

2800×1202 230 KB

After you acquire the token, include it in the authorization header for every request using Key scheme. Replace <your_token_here> with your acquired token; the Key scheme can be omitted:

Authorization: Key <your_token_here>

Acquire and use short-lived tokens

To acquire a short-lived token, make a POST request to the following endpoint:

POST /v1/Account/token

with the following request body:

{
  "username": "your_email",
  "password": "your_password"
}

Where:

  • username: your Onix Work’s account email address.
  • password: your Onix Work’s account password.

Response:

Status code Response body Description
200 A single JSON string. A token in JSON string format, and it will expire in 60 minutes.
400 Error response object with title “Bad request” and status 400. Incorrect user credentials or incorrect request body object.

To use short-lived token, add the HTTP Authorization header with Bearer scheme:

Authorization: Bearer <token>

After acquiring the security token successfully, attach the token in the authorization header for every request, using Bearer scheme. Replace <your_token_here> with your acquired token:

Authorization: Bearer <your_token_here>

Use the token in Swagger

  1. Open Swagger for the environment you want to use.
  2. Select Authorize.
  3. Enter the authorization scheme followed by your token, such as Key <token> or Bearer <token>.
  4. Select Authorize to apply it.

You can now test Onix API requests.

API best practices

We recommend these practices:

  • Refresh short-lived tokens: Periodically acquire new short-lived tokens to ensure continuous access.
  • Safeguard your tokens: Treat tokens as sensitive information and store them securely.
  • Check token expiry dates: Replace long-lived tokens before they expire to ensure continuous access.

Important: Long-lived tokens are specific to your company. Please prioritize the security of this special token.

Terminology

  • Onix API — the modern version of the API designed for interacting with Onix Work efficiently.

  • The Onix Work Web API or Web API — the earlier version of the API for interacting with Onix Work. Deprecated.

  • Production environment — the main environment, and it contains your company’s data. Data here is stored permanently.

  • Sandbox environment — the playground environment. We recommend developers to test on this environment. Please be advised that the data within the sandbox environment is temporary and undergoes periodic restoration from the production environment in accordance with Onix Work’s scheduled processes.

  • The Onix Work system or the system — represents the Onix API or Onix Work in general.

  • Your system — represents you or your software using Onix API.

  • Onix Work — represent the Onix Work platform, typically Onix Work website via Onix Work URL (see Overview).

  • Order — a container that holds multiple order lines. The objective is to create multiple equipment units once the order is delivered (processed).

  • Order line — contains information to create equipment which has the same product type, properties, …

  • Language codes — integer numbers represent languages used in Onix Work system. This is useful if you are developing multilingual software. When an endpoint has languageCode as an optional query parameter/field, the Onix Work system will use English as the default language. Supported languages with language codes:

    • Norwegian – 0.
    • English – 1.
    • Swedish – 3.
    • Danish – 4.
    • Spanish – 7.

  • Company links — your company’s custom definition list to map between your system’s internal IDs (external IDs in Onix Work) for your customer companies and the Onix Work company IDs. There are two types of links: supplier and customer. When specifying IDs in the request body, make sure that the provided external ID exists in the company links with the correct link type.
    To manage company links, open Onix Work on a browser, then navigate to: Settings > System > External linking > Company links tab.

  • Contact links — same as company links, but for contacts.
    To manage contact links, open Onix Work on a browser, then navigate to:
    Settings > System > External linking > Contact links tab.

  • External ID — a term used by Onix Work typically referring to your system’s internal ID.

  • Workflow — a workflow is a customized set of steps defined by your company to track specific progress. Currently, there are two types of workflows: order and order line. You can manage the workflows of your company by navigating to the Onix Work using the Onix Work URL, then: Settings > System > Workflow > Order/Order line.

  • Orders module — one of the main modules in Onix Work, the main purpose is to create and manage orders and order lines.

  • Settings module — one of the main modules in Onix Work, it helps users control different types of preferences for their company.

  • Your company­ — current user logged in the company via tokens.

  • Customer company (in order endpoints) — refer to your system’s customer company.

  • Unique equipment — a class of equipment that is not non-unique (see below), countable, distinctive, and reusable. Borrowed equipment must be returned to the warehouse.

  • Non-unique equipment — a class of equipment that is either consumable goods, stock goods or part.

  • Consumable goods — uncountable items, such as liquids or gases, that cannot be returned to the warehouse. Consumable goods doesn’t have a serial number or a batch number.

  • Stock goods — countable items, often small and trivial, such as nails and screws, and are usually not intended to return to the warehouse. Stock goods doesn’t have a serial number or a batch number.

  • Part — countable items, often components that can combine with other parts to create a complete product.

  • Main equipment — it is formed by combining multiple sub equipment.

  • Sub equipment — component equipment, that can combine with other sub equipment (in main equipment) to create complete equipment (main equipment).

  • Process (an order line property) — corresponds to the Process field on an order line on Onix Work. It defines the action when processing the order or the order line on Onix Work. Supported values are:

    • No action – 1
    • Create equipment – 2.
    • Create equipment and job – 3.
    • Create equipment and file job – 4.

Related

The order APIs

  • Part 1: create and update an order, an order line and numbering an order line.
  • Part 2: update an order line’s properties and form properties.
  • Part 3: how to migrate from Web API to Onix API.
  • Part 4: create and update grouped order lines.

Other APIs

If you encounter any issues or have questions, kindly describe your concern and:

  • Send an email to support@onix.com, or
  • Create a topic in Q&A to receive assistance from all Community members.
1 Like
Onix API - Transfer orders (part 3/4) - Migrate from Web API to Onix API
Define company settings in the Settings module
Onix API – Delete order lines
Onix API - Transfer orders (part 2/4) - Update order line's properties and form properties
Onix API – Transfer products
Onix API - Transfer orders (part 1/4) - Create an order or order line
2026 Winter release notes