# Onix API – Transfer products

**URL:** <https://community.onix.com/t/onix-api-transfer-products/1214>\
**Category:** Knowledge base\
**Tags:** official, onix-api\
**Created:** [September 27, 2024, 12:11pm UTC](https://community.onix.com/t/onix-api-transfer-products/1214 "2024-09-27T12:11:22Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![phuong.duong](https://dub1.discourse-cdn.com/flex013/user_avatar/community.onix.com/phuong.duong/32/1316_2.png) [@phuong.duong](https://community.onix.com/u/phuong.duong)\
**Post date:** [September 27, 2024, 12:11pm UTC](https://community.onix.com/t/onix-api-transfer-products/1214/1 "2024-09-27T12:11:22Z")

</div>

# 1. Overview

The product APIs allow you to create a large number of products with significantly less effort compared to manually creating them in Onix Work. Here is how to create an product using Onix API:

- Initially, create the product by making a POST request to the endpoint:  
**`POST /v1/company/products`** (see section 2. Create or update a product)  
If successful, the system will return a unique productId.

- Proceed to add properties into the product using:  
**`POST /v1/company/products/properties`** (see section 3. Add or update product’s properties)

- Proceed to add forms into the product using:  
**`POST /v1/company/products/forms`** (see section 4. Add or update product’s forms.)

- Proceed to update forms’ properties in the product using:  
**`POST /v1/company/products/form-properties`** (see section 5. Update forms’ properties.)

Here’s a table showing models used by the endpoints:

| Endpoint | Model |
| --- | --- |
| **`POST /v1/company/products`** | ProductInfo |
| **`POST /v1/company/products/properties`** | ProductPropertiesInfoDto |
| **`POST /v1/company/products/forms`** | ProductFormInfoDto |
| **`POST /v1/company/products/form-properties`** | ProductFormPropertiesInfoDto |

# 2. Create or update a product

## API overview

| | |
| --- | --- |
| Endpoint | **`POST /v1/company/products`** |
| Description | Create or update a product |
| Usage | Call this API to create a product and obtain productId from the Onix Work system. |
| Return | The Onix Work system ID of newly created/updated product ID.   
 Return type: int. |

## Prerequisite

It must retrieve the control category through the endpoint: **`GET /v1/company/control-categories`**

## Request parameters and body

Differences between create and update mode:

- Create: To create a product, omit the productId field and provide a unique productNo. The importId is optional.
- Update: To update an order, provide either the orderId, importId, or productNo. These values must already existed in the Onix Work system for your company.

When a field value is null, it follows the rules explained in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2), if no specific rules are mentioned.

The corresponding request body type can be found at [Swagger UI](https://api.onix.com/swagger/index.html), model ProductInfo.

| Field | Data type | Required | Description & Constraints |
| --- | --- | --- | --- |
| `productId` | int | No\* | The Onix Work system’s product ID.  
 To update a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: `productId` \> `importId` \> `productNo` |
| `importId` | string | No\* | Constraint: length ≤ 50.  
 Your system’s product ID (optional).  
 This field can be used to identify the product in the Onix Work system.  
 Typically used for creating or updating products. |
| `productNo` | string | Yes | Constraint: length ≤ 250.   
 Your system’s product number.  
 This field can be used to identify the product in the Onix Work system.  
 Typically used for creating or updating products. |
| `statusId` | int | No | `statusId` is the enum with values:   
 1 – Dynamic   
 2 – Draft   
 3 – Approved   
 4 – New from ERP |
| `status` | string | No | The description of the specified `statusId` value, translated by the user login language when displaying in the UI.   
 If this field has a value in the body request, ignore it. |
| `active` | boolean | No | The active status of product. There are 2 states: _true_ or _false_ |
| `controlCategoryId` | int | No | The ID of control category.   
 Get this value from API: **`GET /v1/company/control-categories`**   
 Note that the Onix API won’t support removing this field’s data, but users can do it manually if needed. |
| `controlCategoryDescription` | string | No | The description of the specified `controlCategoryId` value, translated by the user login language when displaying in the UI.  
 If this field has a value in the body request, ignore it. |
| `controlcategoryDescAndComment` | string | No | The description & comment of the specified `controlCategoryId` value, translated by the user login language when displaying in the UI.  
 If this field has a value in the body request, ignore it. |
| `placement` | string | No | Constraint: length ≤ 50.  
 The placement of the product |
| `type` | string | No | Constraint: length ≤ 50.  
 The equipment type. |
| `model` | string | No | Constraint: length ≤ 100.   
 The equipment model.  
 If the `model` doesn’t include in the body request or include with a null value.   
   
 When creating a new product, the `model` will be obtained from the from `description` field.  
 When updating the existing product, the `model` will be unchanged whether the `description` field has value or not. |
| `description` | string | No | Constraint: length ≤100.   
 The original ERP description. When creating a new product that is also the Model. |
| `wll` | string | No | Constraint: length ≤ 50.   
 The Working load limit (WLL) of product. |
| `swl` | string | No | Constraint: length ≤ 50.  
 The Safety working load (SWL) of product. |
| `comment` | string | No | Constraint: length ≤ 4000.   
 Comment on equip. |
| `dealer` | string | No | Constraint: length ≤ 100.   
 The dealer of product. |
| `prodAccTo` | string | No | Constraint: length ≤ 250.   
 The produced acc. to of product. |
| `producer` | string | No | Constraint: length ≤ 100.  
 The producer of product. |
| `prodYear` | string | No | Constraint: length ≤ 10.  
 The production year of product. |
| `quantityUsage` | int | No | `quantityUsage` is the enum with values:   
 0 – Indicate the _Unique equipment_ or _Part_  
 1 – Indicate the _Stock goods_  
 2 – Indicate the _Consumable goods_ |
| `productGroup` | boolean | No | Whether the current product is a product group. There are 2 states: _true_ or _false_ |
| `connectedProductGroupId` | int | No | The product group ID of this product |
| `productClassId` | int | No | `productClassId` is the enum with values:  
 0 – Indicate the _Unique equipment_  
 1 – Indicate the _Stock goods_  
 2 – Indicate the _Consumable goods_  
 3 – Indicate the _Part_ |
| `downloadToOnixInspect` | boolean | No | There are 2 states: There are 2 states: _true_ or _false_ |
| `useFromEquipment` | boolean | No | There are 2 states: There are 2 states: _true_ or _false_ |
| `testedAccTo` | string | No | Constraint: length ≤ 100.   
 The test acc. to of product. |
| `ProcessId` | int | No | `processId` is the enum with values:   
 1 - Indicate the _No action_   
 2 - Indicate the _Create equipment_   
 3 - Indicate the _Create equipment and job_   
 4 - Indicate the _Create equipment and file job_ |
| `jobComment` | string | No | Constraint: length ≤ 4000.   
 The comment on job. |

## Response

| Status code | Response body | Description |
| --- | --- | --- |
| 200 | A 32-bit integer. | A product has been created or updated successfully.   
 The integer in the response body is the Onix Work system’s `productId`. |
| 400 | The system’s standard error response object. | See examples of error responses in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2). |

## Examples

We will use Swagger UI to create a product.

- First, obtain a security token and authorize the Swagger requests. See [Authentication](https://community.onix.com/t/onixapi-get-started/602#p-980-h-3-authentication-6) for more information.

- Next, make a request to the endpoint, the request body looks like:

```json
{
    "importId": "ERP_Import/P0001",
    "productNo": "ERP_Import/P0001",
    "statusId": 1,
    "active": true,
    "controlCategoryId": 127
  }

```

The system responsed with status code of 200, the response body is the system’s productId:

```auto
214011

```

We will use these values for examples in the next sections:

- `importId`: “ERP\_Import/P0001”.
- `productNo`: “ERP\_Import/P0001”.
- `productId`: 214011.

The product has been created successfully. Let’s check the product: Navigate to [Onix Work](https://prod.onix.com/), use the `productNo` value in the request above to search in the **Product no.** search field. The first result is our newly created product.

 ![image](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/b/b563772314140c0094e7e261f90c769f88544658.png)

## Integrating suggestions

Based on the prerequisite & API design, we suggest integrating the functionality to create or update a product using the key `productNo` as illustrated in the UML diagram below.

1. `GET` control category list
2. `POST` to create a product
3. `POST` to update a product if needed.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/c/ce61f8c01c0d02276979332f6a1451f4b016d8d7.png)

# 3. Add or update properties for a product

## API overview

| | |
| --- | --- |
| Endpoint | **`POST /v1/company/products/properties`** |
| Description | Add or update properties for a product |
| Usage | Call this API to add or update properties for a product. |
| Return | Return type: boolean. |

## Prerequisite

- Products have been already created. Refer to section 2. Create or update a product for further details.
- It must retrieve properties through the endpoint: `GET /v1/company/properties`

## Request parameters and body

The corresponding request body type can be found at the [Swagger UI](https://api.onix.com/swagger/index.html), model `ProductPropertiesInfoDto` for the main request body and `PropertyInfo` for the properties model.

Differences between add and update mode:

- Add: If the properties are not yet included in the product but exist in the properties list in Onix Work, they will be added.
- Update: If the properties were previously included in the product, their values will be updated based on the corresponding data in the request.

When a field value is null, it follows the rules explained in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2), if no specific rules are mentioned.

The corresponding request body type can be found at the [Swagger UI](https://api.onix.com/swagger/index.html), model `ProductPropertiesInfoDto`.

| Field | Data type | Required | Description & Constraints |
| --- | --- | --- | --- |
| `productId` | int | No\* | The Onix Work system’s product ID.   
 To add or update properties for a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: productID \> importId \> productNo |
| `importId` | string | No\* | Constraint: length ≤ 50.   
 Your system’s product ID.   
 Typically used for adding or updating properties for a product. |
| `productNo` | string | No\* | Constraint: length ≤ 250.   
 Your system’s product number.   
 Typically used for adding or updating properties for a product. |
| `properties[index].languageCode` | Int | No | The language of the property in the product.   
 Available values: 0, 1, 3, 4, 6, 7, 9 where:   
 0: Norwegian  
 1: English  
 3: Swedish  
 4: Danish  
 6: Deutsch  
 7: Spanish  
 9: Portuguese |
| `properties[index].description` | string | Yes | The description of properties.   
 When adding or updating the properties, the system will find all properties that match their names and translated names according to the `languageCode` specified in the request description. |
| `properties[index].value` | string | No | The property value. |

## Response

| Status code | Response body | Description |
| --- | --- | --- |
| 200 | A boolean. | Properties in the product have been added or updated successfully. |
| 400 | The system’s standard error response object. | See an examples of error responses in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2). |

## Examples

Let’s use one of the following keys: `productId`, `importId`, or `productNo` to add or update properties for a product.

- `importId`: “ERP\_Import/P0001”.
- `productNo`: “ERP\_Import/P0001”.
- `productId`: 214011.

First, let’s examine the properties that the product has been using for better visualization:

- Currently, the product only has a property called **ABAX Serial Number**.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/9/95b7a92f1a63d10ea518265c2978610af2614dd3.png)

- And in the properties list, it has a property called **Color**.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/d/d807cb98350308aa0f3b467b27599840223ddf06.png)

To add/update the product’s properties, make a request with the request body below, with `languageCode` is English (see [Onix API terminology](https://community.onix.com/t/onixapi-get-started/602#p-980-h-5-terminology-10)). In this example, we use the key `productNo`

```json
{
  "productNo": ERP_Import/P0001,
  "properties": [
    {
      "languageCode": 1,
      "description": "Color",
      "value": "Red"
    },
    {
      "languageCode": 1,
      "description": "ABAX Serial Number”,
      "value": "SN-4521"
    }
  ]
}

```

The system responsed with status code of 200, the response body indicates where the request was successful or not:

```json
true

```

The properties have been added or updated successfully. Let’s check the results in Onix Work: Navigate to the product we have just created in section 2 and open **Properties** tab. The properties have been added/updated according to the request.

 ![image](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/0/0808984456c3f99567bbe09fcc755080b227e900.png)

## Integrating suggestions

Based on the prerequisite & API design, we suggest integrating the functionality to add or update properties for a product using the key `productNo` as illustrated in the UML diagram below.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/d/dad3790ca53c66f5feda7657ce9454f7be245051.png)

# 4. Add or update a product’s forms

## API overview

| | |
| --- | --- |
| Endpoint | **`POST /v1/company/products/forms`** |
| Description | Add or update forms for a product |
| Usage | Call this API to add/update forms for a product. |
| Return | Return type: boolean. |

## Prerequisite

- Products were created. Refer to section 1. Create or update a product for further details.
- It must retrieve forms through the endpoint: `GET /v1/company/forms`
- It must retrieve job types through the endpoint: `GET /v1/company/job-types`

## Request parameters and body

The corresponding request body type can be found at the [Swagger UI](https://api.onix.com/swagger/index.html), model `ProductFormInfoDto` for the main request body and `FormInfoDto` for the forms model.

Differences between add and update mode:

- Add: If the forms are not yet included in the product but exist in the forms list in Onix Work, they will be added.
- Update: If the forms were previously included in the product, their values will be updated based on the corresponding data in the request.

When a field value is null, it follows the rules explained in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2), if no specific rules are mentioned.

The corresponding request body type can be found at the [Swagger UI](https://api.onix.com/swagger/index.html), model `ProductFormInfoDto`.

| Field | Data type | Required | Description & Constraints |
| --- | --- | --- | --- |
| `productId` | int | No\* | The Onix Work system’s product ID.   
 To add or update forms for a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: productID \> importId \> productNo |
| `importId` | string | No\* | Constraint: length ≤ 50.   
 Your system’s product ID.   
 Typically used for adding or updating forms for a product. |
| `productNo` | string | No\* | Constraint: length ≤ 250.   
 Your system’s product number.   
 Typically used for adding or updating forms for a product. |
| `forms[index].formId` | Int | Yes | The form ID.   
 Get this value from API: `GET /v1/company/forms` |
| `forms`[index].languageCode | Int | No | The language of the form in the product.   
 Available values: 0, 1, 3, 4, 6, 7, 9 where:   
 0: Norwegian  
 1: English   
 3: Swedish  
 4: Danish   
 6: Deutsch  
 7: Spanish  
 9: Portuguese |
| `forms[index].jobTypeId` | Int | No | The job type of the form in the product.   
 Get this value from API: `GET v1/company/job-types` |

## Response

| Status code | Response body | Description |
| --- | --- | --- |
| 200 | A boolean. | Forms in the product have been added or updated successfully. |
| 400 | The system’s standard error response object. | See an examples of error responses in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2). |

## Examples

Let’s use one of the following keys: `productId`, `importId`, or `productNo` to add or update forms for a product.

- `importId`: “ERP\_Import/P0001”.
- `productNo`: “ERP\_Import/P0001”.
- `productId`: 214011.

First, let’s examine the forms that the product has been using for better visualization:

- Currently, the product only has a form **Inspection report**.
- In the forms list, it has a form called **Declaration of Conformity** that you would like to add to the corresponding product.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/d/dbc8e2193ef67d90a54b354757a5cad31f4fb537.png)

To add/update the product’s forms, make a request with the request body below, with `languageCode` is English (see [Onix API terminology](https://community.onix.com/t/onixapi-get-started/602#p-980-h-5-terminology-10)). In this example, we use the key `productNo`

```json
{
  "productNo": ERP_Import/P0001,
  "forms": [
    {
      "formId": 1, // Inspection report
      "languageCode": 1, // English
      "jobTypeId": 2 // 
    },
    {
      "formId": 34, // EKH certificate
      "languageCode": 1, // English
      "jobTypeId": 1 // Initial control
    }
  ]
}

```

The system responsed with status code of 200, the response body indicates where the request was successful or not:

```json
true

```

The forms have been added or updated successfully. Let’s check the results in Onix Work: Navigate to the product we have just created in section 2 and click on the tab **Forms**. The forms have been added or updated according to the request.

 ![image](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/6/60877ad96bf38cdb4fd047eed41d995a51e1fcbd.png)

## Integrating suggestions

Based on the prerequisite & API design, we suggest integrating the functionality to add or update forms for a product using the key `productNo` as illustrated in the UML diagram below.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/d/d2e1c2c277af86440da9dbb81a901aa633cd57a6.png)

# 5. Update forms’ properties of a product

## API overview

| | |
| --- | --- |
| Endpoint | ` **POST /v1/company/products/form-properties** ` |
| Description | Update properties of forms in a product |
| Usage | Call this API to properties of forms in a product. |
| Return | Return type: boolean. |

## Prerequisite

- Products have already been created. Refer to section 2. Create or update a product for further details.
- Forms were added into the product. Refer to section 4. Add or update forms for a product for further details.
- It must retrieve forms’ properties through the endpoint: `GET /v1/company/form-properties`

## Request parameters and body

The corresponding request body type can be found at the [Swagger UI](https://api.onix.com/swagger/index.html), model `ProductFormPropertiesInfoDto` for the main request body and `FormPropertyKeyValueInfo` for the forms’ properties model.

When a field value is null, it follows the rules explained in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2), if no specific rules are mentioned.

The corresponding request body type can be found at the [Swagger UI](https://onixapi.onix.com/swagger/index.html), model `ProductFormPropertiesInfoDto`.

| Field | Data type | Required | Description & Constraints |
| --- | --- | --- | --- |
| `productId` | int | No\* | The Onix Work system’s product ID.   
 To update forms’ properties for a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: productID \> importId \> productNo |
| `importId` | string | No\* | Constraint: length ≤ 50.   
 Your system’s product ID.   
 Typically used for adding or updating forms’ properties for a product. |
| `productNo` | string | No\* | Constraint: length ≤ 250.   
 Your system’s product number.   
 Typically used for adding or updating forms’ properties for a product. |
| `properties[index].key` | string | Yes | Key of the form property.   
 Get it through this endpoint: `GET /v1/company/form-properties` |
| `properties[index].value` | string | No | Value of the form property. |

## Response

| Status code | Response body | Description |
| --- | --- | --- |
| 200 | A boolean. | Forms’ properties of the product have been updated successfully. |
| 400 | The system’s standard error response object. | See an examples of error responses in [API requests and responses](https://community.onix.com/t/onixapi-get-started/602#p-980-h-2-api-requests-and-responses-2). |

## Examples

Let’s use one of the following key: `productId`, `importId`, or `productNo` to update forms for a product.

- `importId`: “ERP\_Import/P0001”.
- `productNo`: “ERP\_Import/P0001”.
- `productId`: 214011.

First, let’s examine the forms that the product has been using for better visualization. Currently, the product has a form **Declaration of Conformity**.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/a/aa822bd1be6157006cfc8f64c9cd0e23a0da1c9f.png)

To update the forms’ properties in the product, make a request with the request body below. In this example, we use the key `productNo`

```json
{
  "productNo": ERP_Import/P0001,
  "properties": [
    {
      "key": "ApiKey_ResponsibleTechnical",
      "value": "Thomas"
    },
    {
      "key": "ApiKey_TypeApprovalCertificateNo",
      "value": "4324"
    }
  ]
}

```

The system responsed with status code of 200, the response body indicates where the request was successful or not:

```json
true

```

The forms’ properties have been updated successfully. Let’s check the results in Onix Work: Navigating to the product we have just created in section 2 and click on the tab **Forms**.  
The forms’ properties in the product have been updated according to the request.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/5/50aa9101d17c11a1abeb562265d2d621d170342d.png)

## Integrating suggestions

Based on the prerequisite & API design, we suggest integrating the functionality to update forms’ properties in a product using the key `productNo` as illustrated in the UML diagram below.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/d/d9d681bac09fcfe4bd3bc9ccd2e853c7c64b1eaf.png)