Implementation guide for Products API v2


The Products API can suit different purposes. On this page you will find a step-by-step guide on which endpoints to use, in what sequence and how to structure the requests in order to achieve the desired results. The workflows presented on this page are just an example for the most common use cases we have seen in our experience with implementation of the Products API.

Creating a product


One of the most common uses of the Products API is for enriching the goBIM product catalogue of the manufacturer with more products. You can create both a single product and a grouping of multiple products in a product line. Here are the steps you need to follow in order to make a single product:

  1. Use the Create product endpoint

    The Create product endpoint creates products, based on a number of essential attributes, describing the product – its name, construction object type, specific type and country of distribution, as well as identifiers and additional optional data about it. Here’s an example of a json for a product which is sold in Norway:

    {
      "country": "NO",
      "name": "My test product",
      "gtin": "1234567891234",
      "spn": "654321",
      "constructionObjectGuid": "string",
      "specificType": “Regular”,
      "identifiers": [
        {
          "name": “nobbnr”,
          "value": "123456789"
        }
      ]
    }

    Important to note: In the Create product endpoint response, we return the Cobuilder ID of the newly created product. The Cobuilder IDs are the unique identifiers of the products in our system and need to be provided each time when an action concerns a particular product - creating properties, updating, deleting or getting data.

    Example response:

    {
      "id": 1000000,
      "name": "My test product",
      "description": "Description preview",
      "manufacturerName": "Cobuilder",
      "countryId": NO,
      "spn": "654321",
      "gtin": "1234567891234",
      "identifiers": [
        {
          "value": "123456789",
          "name": "nobbnr"
        }
      ],
      "specificType": "Regular",
      "isExpired": false,
      "createdOn": "string",
      "changedOn": "string",
      "accountId": "string",
      "ParentId": 0,
    }

  2. Use the Create property values endpoint

    After your product is created, you can enrich the product with data further by providing values for its properties. F.ex. specify the height and width of the product.

    Important to note: The properties of the product depend on the its construction object type. The properties which are part of the construction object template can either be taken from the Templates API or can be provided by Cobuilder in another format. The attributes which are defined in the construction object template (construction object, properties, units, predefined values) have guids. The Products API relies on these system guids and providing an incorrect guid or not providing any guid whatsoever will return an error.

    Each property also has a set data type. We do not require the data type of the property to be stated in the request when creating or updating properties, but a validation will be done after the value is sent to us. If the value does not comply with the correct data type, an error will be returned.

    The request body needs to be adjusted depending on what kind of property needs to be created.

    Example request for a property with data type string:

    [
      {
        "propertyGuid": "string",
        "unitGuid": "string",
        "values": [
          {
            "value": "My test string value",
          }
        ]
      }
    ]

    Example request for a property with data type integer:

    [
      {
        "propertyGuid": "string",
        "unitGuid": "string",
        "values": [
          {
            "value": "100",
            "operator": "eq"
          }
        ]
      }
    ]

    Example request for a property with data type integer with a range value.

    Important to note: the lower value should be passed first.

    [
      {
        "propertyGuid": "string",
        "unitGuid": "string",
        "values": [
          {
            "value": "100",
            "operator": "gt"
          },
          {
            "value": "200",
            "operator": "lt"
          },
        ]
      }
    ]

    Example request for a property with a predefined value:

    [
      {
        "propertyGuid": "string",
        "unitGuid": "string",
        "values": [
          {
            "valueGuid": "string",
          },
          {
            "valueGuid": "string",
          }
        ]
      }
    ]

Using product lines


  1. Create a product with specific type "Product line"

    In order to create a product line, you need to provide the same essential attributes, describing any other product – its name, construction object type, specific type and country of distribution, as well as identifiers and additional optional data about it. Use the same endpoint as creating a single product – the Create product endpoint. The difference is in the specifc type of the product - this time use "ProductLine".

    Here’s an example of a json for a product line which is sold in Norway:

    {
      "country": "NO",
      "name": "My test product",
      "gtin": "1234567891234",
      "spn": "654321",
      "constructionObjectGuid": "examplestring",
      "specificType": "ProductLine",
      "identifiers": [
        {
          "name": "nobbnr",
          "value": "123456789"
        }
      ]
    }

    Important to note: In the Create product endpoint response, we return the Cobuilder ID of the newly created product. The Cobuilder IDs are the unique identifiers of the products in our system and need to be provided each time when an action concerns a particular product - creating properties, updating, deleting or getting data. In this case, the Cobuilder ID is what you will need to provide when connecting single products under the product line. This ID will also be provided in the details of products and other product lines, belonging to this product line via the parameter ParentId.

    Here's an example response:

    {
      "id": 1000000,
      "name": "My test product",
      "description": "Description preview",
      "manufacturerName": "Cobuilder",
      "countryId": NO,
      "spn": "654321",
      "gtin": "1234567891234",
      "identifiers": [
        {
          "value": "123456789",
          "name": "nobbnr"
        }
      ],
      "specificType": "ProductLine",
      "isExpired": false,
      "createdOn": "string",
      "changedOn": "string",
      "accountId": "string",
      "ParentId": 0,
    }

  2. Change the product type to Product line

    In case there is an already existing product in your catalogue that you want to turn into a product line, you can do so by using the Update product endpoint. It can change the specific product type of a product that has been created as "Regular". You can change it from “Regular” to “ProductLine” and vice versa.


  3. Add existing products to a product line

    If the products that belong to the product line aren’t created yet, begin with the Create product endpoint in order to create them. If both the product line and the products that should belong to it are available in your ctalogue, use the Add children to product line endpoint to connect them to one another.

    Important to note:

    • The product line and the products under it need to have the same construction object
    • You can assign a product line as a part of another product line. The maximum levels such a hierarchy can have is 3
    • Property values, filled in on the parent level will be automatically added on the children levels. See Step 7 for more information

    In the URL – provide the product line Cobuilder ID. In the request body – provide the Cobuilder IDs of the products which should be a part of the product line.


  4. Remove products from a product line

    If you need to remove products from a product line, use the Remove children from product line endpoint by putting the product line ID in the URL and providing the IDs of the product you want to remove from the line in the request body.


  5. Search for product lines

    If you are specifically searching for product lines within your product catalogue, you can use the Product Search endpoint to filter the products which have specific type "ProductLine". As the hierarchic structure of a product line can have multiple levels and sub-lines, you can additionally filter the results, so that you only get the top level product lines - the one that do not belong to any other line.

    Here's an example of how the request body will look like:

    {
      "filtration": {
        "specificTypes": [
          "ProductLine"
        ],
        "includeExpired": true,
        "filterTopLevelProductLines": true
      },
      "pagination": {
        "skip": 0,
        "take": 50
      }
    }                
                

  6. Get product line children

    In order to check which products belong to a product line, use the Get product line children endpoint by putting the product line ID in the request URL.

  7. Manage property values for a product, which is a part of a product line – Create, Get, Update

    Property values entered on the parent level will be returned for all products and product lines, which belong to that parent product line. The ParentID parameter in the response will be filled in with the parent product line’s Cobuilder ID, in case the property value is inherited.

    Here's an example:

    The product line “Semi-glossed Cobuilder Paint” (Cobuilder ID: 111111) has the characteristic “finish”, which is common for all products of that group. The Get property values endpoint will return the following:

    [
      {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "finish",
        "propertyDefaultTitle": "finish",
        "unitTitle": "unitless",
        "unitDefaultTitle": "unitless",
        "parentId": 0,
        "values": [
          {
            "value": "semi-gloss",
            "dataType": "string"
          }
        ]
      }
    ]
    

    The regular product “Semi-glossed Cobuilder Paint 1L” is a part of the “Semi-glossed Cobuilder Paint” product line. When the product was attached, it automatically got the property values, entered on the higher hierarchic level. The response you will get for it will be the following:

    [
      {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "finish",
        "propertyDefaultTitle": "finish",
        "unitTitle": "unitless",
        "unitDefaultTitle": "unitless",
        "parentId": "111111",
        "values": [
          {
            "value": "semi-gloss",
            "dataType": "string"
          }
        ]
      }
    ]
    

    To add a new property value to the child product, you follow the same flow as with any other product. Send a request through the Create property values endpoint to create a new value. Here’s the GET response after we have added a property value for “color” only on the child product:

                    [
      {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "finish",
        "propertyDefaultTitle": "finish",
        "unitTitle": "unitless",
        "unitDefaultTitle": "unitless",
        "parentId": "111111",
        "values": [
          {
            "value": "semi-gloss",
            "dataType": "string"
          }
        ]
      }
    {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "color",
        "propertyDefaultTitle": "color",
        "unitTitle": "unitless",
        "unitDefaultTitle": "unitless",
        "parentId": 0,
        "values": [
          {
            "value": "Blue",
            "dataType": "string"
          }
        ]
      }
    ]
                

    When there is a value filled in on the parent level and you want to change it on a particular child product, you can follow the same flow as with any other product – use the Update property values endpoint to change that value.

    Important to note: Changing the property value on the child product level, will NOT change the value entered on the parent level. The property value will be overwritten only for the particular product with was updated and the parent value will no longer be visible for that product. If you want to change a value for the whole product line, you should update the product where it was originally entered – the parent product line.

    Here’s an example for a property value that has been updated on the child level:


    Get Property Values response for the product line “Semi-glossed Cobuilder Paint”:

               [
      {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "packaging size",
        "propertyDefaultTitle": "packaging size",
        "unitTitle": "litre",
        "unitDefaultTitle": "litre",
        "parentId": 0,
        "values": [
          {
            "value": "1",
            "operator": "gt"
            "dataType": "float"
          }
          {
            "value": "10",
            "operator": "lt"
            "dataType": "float"
          }
    
        ]
      }
    ]
    
           

    Get Property Values response for the child product “Semi-glossed Cobuilder Paint 1L”:

               [
      {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "packaging size",
        "propertyDefaultTitle": "packaging size",
        "unitTitle": "litre",
        "unitDefaultTitle": "litre",
        "parentId": 0,
        "values": [
          {
            "value": "1",
            "operator": "eq"
            "dataType": "float"
          }
        ]
      }
    ]
    
           

Updating existing products


  1. Updating product name or status

    After a product is created, the only essential data that can be updated and changed is the product name, specific type and status.

    To change a product’s name, use the Update product endpoint.

    The same endpoint can be used to change a product's specific type from "Regular" to "ProductLine" or vice versa.


    To change a product’s status - expire it or activate it anew, use the Update product status endpoint.


  2. Adding new properties

    For adding new properties for which no values were previously provided, use the Create property values endpoint.


  3. Updating property values

    For updating or editing a property value that was previously entered, use the Update property values endpoint.

    If there are multiple products with the same SPN identifier and same characteristics, but different countries of distribution, you can also edit their properties in bulk, by using the Update property values in bulk by SPN endpoint.


  4. Deleting properties

    You can delete values for properties, by providing the guid of the property that needs to be deleted, through the Delete property values endpoint.

Getting product data


You can go about getting product data in a different order, depending on what kind of information you need. The workflow described in this section is an example one and you can use all GET endpoints in a different order, depending on your needs. The only thing you need to provide to access the information for a product is its Cobuilder ID (“Id”).


  1. Search for products in the product list

    The search endpoints can be modified, depending on your needs. For more information and examples on how to use them, go back to the “Searching for products” section.

    Important to note: No matter how you structure your search, the returned results will include the products’ Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

    Example response:

    {
      "results": [
        {
          "id": 1000000,
          "country": "NO",
          "name": "My example product",
          "description": "string",
          "spn": "12345",
          "gtin": "123456789",
          "isExpired": false,
          "specificType": "Regular"
        }
      ],
    }                
                

  2. Get information about the product

    To get the essential information for the product - name, identifiers, country of distribution, ID of the parent product line if it belongs to one, use the Get Product Details endpoint. To get the information in a specific language, provide a culture code in the request URL.


  3. Get a product’s construction object

    To get the product’s construction object type, use the Get Product Details endpointGet construction object endpoint. To get the information in a specific language, provide a culture code in the request URL.


  4. Get a product’s properties

    To get all of the product’s property values, use the Get property values endpoint. To get the information in a specific language, provide a culture code in the request URL.

    Important to note: For products, which are part of a product line, the response will contain both values, filled in for that particular product, as well as values, filled in on the product lines that the product belongs to. Values, which are inherited from a higher hierarchic level will have the ParentID paramenter filled in with the Cobuilder ID of the product line it was originally filled in for.

    Here’s two examples:


    Property which belongs to the particular product. The “ParentId” is 0:

                    [
      {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "finish",
        "propertyDefaultTitle": "finish",
        "unitTitle": "unitless",
        "unitDefaultTitle": "unitless",
        "parentId": 0,
        "values": [
          {
            "value": "semi-gloss",
            "dataType": "string"
          }
        ]
      }
    ]
    
                

    Property which belongs to a product line that the particular product is a part of. ParentId is filled in with the Id of the parent product line where the property was inherited from:

                    [
      {
        "propertyGuid": "ExampleString",
        "unitGuid": "ExampleString",
        "propertyTitle": "finish",
        "propertyDefaultTitle": "finish",
        "unitTitle": "unitless",
        "unitDefaultTitle": "unitless",
        "parentId": "111111",
        "values": [
          {
            "value": "semi-gloss",
            "dataType": "string"
          }
        ]
      }
    ]
                

  5. Get a product’s picture, documents or other attributes

    If you want to access the other data, connected to the product, you can use the different endpoints that are about each asset type:

    To get the information in a specific language, provide a culture code in the request URL.

Searching for products


The Products API offers two kinds of product searches – one which is based on the main product data – identifiers, country of distribution, product specific type, and another one which is based on the product’s construction object type and its properties.

Important to note: However, you structure your search, the returned results will include the products’ Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

Here’s how you can use the search endpoints:


  1. Search, based on the main product information

    The Product Search endpoint can filter the products in your product list, based on the following criteria:

    • Identifiers - SPN or GTIN
    • Country of distribution
    • Specific product type
    • Status
    • Part of another product line (relevant for product lines only)

    The criteria you don't need can be omitted from the request body. Or, for a more specific search, the parameters can also be combined.

    Example for a search that returns all active products existing on the account:

    {
      "filtration": {
          "includeExpired": false
      }
    }

    Example for a search that returns all active products with country of distribution Norway:

    {
      "filtration": {
        "countries": [
          "NO"
        ],
        "includeExpired": false
      }
    }

    Example for a search that returns a product with country of distribution Norway and has a particular SPN:

    {
      "filtration": {
        "spn": "12345",
        "countries": [
          "NO"
        ],
        "includeExpired": false
      }
    }

    As mentioned above, the returned results will include the products’ Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

    Example response:

    {
      "results": [
        {
          "id": 1000000,
          "country": "NO",
          "name": "My example product",
          "description": "string",
          "spn": "12345",
          "gtin": "123456789",
          "isExpired": false,
          "specificType": "Regular"
        }
      ],
    }                
                

  2. Advanced search, based on additional product characteristics

    The Product Search endpoint can filter the products in your product list, based on the following criteria:

    • Product name
    • Construction object
    • Parent ID (relevant for product lines only)
    • Property values

    The criteria you don't need can be omitted from the request body. Or, for a more specific search, the parameters can also be combined.

    Example for a search that returns all products containing a key word in their name (you need to provide at least 3 characters for the search to work):

    {
      "filtration": {
        "name": "Cobuilder product"
      },
      "pagination": {
        "skip": 0,
        "take": 50
      }
    }
    

    Example for a search that returns all products that have the same construction object:

    {
      "filtration": {
        "constructionObjectGuid": "ExampleString",
      },
      "pagination": {
        "skip": 0,
        "take": 50
      }
    }
    

    Example for a search that returns all products which have a certain property value. Providing the construction object is required when you are searching for property value matches:

    {
      "filtration": {
        "constructionObjectGuid": "ExampleString",
        "parentId": 0,
        "properties": [
          {
            "propertyGuid": "ExampleString",
            "values": [
              {
                "value": "5",
                "operator": "eq"
              }
            ]
          }
        ]
      },
      "pagination": {
        "skip": 0,
        "take": 50
      }
    }
    

    Example for a search that returns all products which have a certain property value and are a part of the same product line:

    {
      "filtration": {
        "constructionObjectGuid": "ExampleString",
        "parentId": "111111",
        "properties": [
          {
            "propertyGuid": "ExampleString",
            "values": [
              {
                "value": "5",
                "operator": "eq"
              }
            ]
          }
        ]
      },
      "pagination": {
        "skip": 0,
        "take": 50
      }
    }
    
    

    As mentioned above, the returned results will include the products’ Cobuilder ID. This is the parameter that you will need to provide in all the GET request URLs, in order to access the information for that product.

    Example response:

    {
      "results": [
        {
          "name": "string",
          "Id": 0,
          "parentId": 0,
          "specificType": "Regular"
        }             
                

Creating a document

The Products API allows enriching your product catalogue with product assets – documents, pictures, BIM objects. You can create documents independently from products or connect them directly to multiple products.

The Create document endpoint creates a document, based on a file to upload and a set of essential attributes, describing the document - name, type, countries where applicable. The available document types and countries are preset and can be found in the Relevant nomenclatures page.

Important to note: One file can only be uploaded once. An error will be returned if another upload of the same file is attempted.

Here’s an example of creating a single document, not connected to a product:

Use content type: multipart/form-data

Example with curl (automatically determines the correct content type)

curl --location --request POST 
"https://api-test.cobuilder.no/products-management/api/v2/documents"
--header "Authorization:Bearer {token}"
--form "file=@"C:\Users\test\Desktop\Documentation.pdf""
--form "Type=Brochure"
--form "Countries=GB"
--form "Countries=NO"
--form "Name=Document name"

Here’s an example of creating a single document, which is connected to a product upon its creation:

curl --location --request POST 
"https://api-test.cobuilder.no/products-management/api/v2/documents"
--header "Authorization:Bearer {token}"
--form "file=@"C:\Users\test\Desktop\Documentation.pdf""
--form "Type=Brochure"
--form "Countries=GB"
--form "Countries=NO"
--form "Name=Document name"
--form "ProductIds=123456"
--form "ProductIds=123457"

Updating a document

After a document is created, the file that was originally uploaded cannot be altered. The metadata for the document can, however, be changed. You can update the name, type and status of the product through the Update document endpoint .

Here’s an example of changing the name and status of the document:

{
  "type": "Warranty",
  "status": "Expired",
  "name": "New name of document"
}

Searching for documents

A document can only be uploaded once. In case you have a product that needs to be connected to a document that was previously created, you can use the Search documents endpoint to browse through the documents that already exist on your account.

You can filter through the documents, based on different criteria like type, name and status. For a translation of the document type, you can also provide a culture code for the target language.

Here’s an example of a search where we want to get only documents with document type Technical Data Sheet and with status Active:

{
  "filtration": {
    "status": "Active",
    "documentTypes": [
      "TechnicalDatasheet"
    ]
  },
  "pagination": {
    "skip": 0,
    "take": 50
  }
}

Relating documents and products

One document can apply to more than one product and the Products API accounts for that with the endpoints for relating and unrelating products and documents.

You have the opportunity to link multiple documents to multiple products or vice versa.

  1. Adding relations between documents and products

    You can link one document to multiple products. Through the Add relations between documents and products endpoint you can do that for more than one documents.

    [
      {
        "productId": 123456,
        "documentId": 1
      },
      {
        "productId": 123457,
        "documentId": 1
      },
      {
        "productId": 123458,
        "documentId": 2
      }
    ]
    

  2. Removing the relations between documents and products

    Sometimes a document needs to be unlinked from one or more products. The Remove relations between documents and products endpoint allows you to do that with multiple documents and products.

    Here’s how you can unlink two documents from a few of their related products:

    [
      {
        "productId": 123456,
        "documentId": 1
      },
      {
        "productId": 123457,
        "documentId": 1
      },
      {
        "productId": 123458,
        "documentId": 2
      }
    ]
    

Deleting a document

If you want to permanently delete a document, you can use the Delete document endpoint.

The ID of the document that is to be deleted should be provided in the URL.

Important to note: If the document is connected to a product, the action will not be completed. Refer to the Remove relations between documents and products endpoint first.