Inventory & Products | CN Codes

Getting CN Codes Data

This document outlines the procedure for making API calls to retrieve CN (Combined Nomenclature) codes data via https://easycms.fi/public_api/get_cn_codes/. CN codes are used for customs and trade classification of goods.

CN Codes Data Retrieval

Retrieve CN codes data effectively using the below API call. Apply the required parameters in the request payload to retrieve CN code information.


Endpoint and Method

  • Endpoint: https://easycms.fi/public_api/get_cn_codes/
  • Method: GET or POST

Parameters | Payload

  • TOKEN (api_key): Your unique API key for authentication. How to Create API Credentials.
  • username: Your login username.
  • password: Your login password.
  • account: Your specific account ID.

Optional Parameters

Parameter Type Description
cn_code_id integer/array Specific CN code ID or array of IDs to retrieve
IN integer/array CN code IDs to include (array or single integer)
NOT_IN integer/array CN code IDs to exclude (array or single integer)
cn_code_value string Search by CN code value (partial match)
search string Search keyword. Performs a partial (LIKE) match across multiple CN code columns. Supports multi-word queries separated by spaces or + — each word must match at least one column (AND logic between words). Case-insensitive. Searchable columns: cn_code_name, cn_code_value, cn_codeNumber, cn_code_id
parent_id integer Filter by parent CN code ID for hierarchical codes
visible integer Filter by visibility (1=visible, 0=hidden). To include hidden CN codes in the response, use show_invisible=1 instead.
show_invisible integer Set to 1 to include CN codes with visible=0 (hidden) in the response. By default, only visible CN codes (visible=1) are returned.
start integer Starting index for pagination (default: 0)
limit integer Number of records to return (default: 50, max: 50)



Understanding CN Code Search

The search parameter enables broad keyword matching across all relevant columns of the CN code record. This is useful for:

  • Quick lookup: Find a CN code by partial name (searches across all language variants stored in cn_code_name).
  • Code search: Find CN codes by their value (cn_code_value), number (cn_codeNumber), or internal ID (cn_code_id).
  • Multi-word search: Use spaces or + to narrow results — e.g., search=610910+cotton will only return CN codes where one word matches "610910" AND another matches "cotton" across any searchable columns.

Each word in the search query is matched independently across all searchable columns using OR within a word, and AND between words.



Call Examples in Different Languages


# Get all CN codes
curl -X GET 'https://easycms.fi/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID' \
-H 'Authorization1: TOKEN'

# Get specific CN code by ID
curl -X GET 'https://easycms.fi/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&cn_code_id=1' \
-H 'Authorization1: TOKEN'

# Search CN codes by keyword (matches cn_code_name, cn_code_value, cn_codeNumber, cn_code_id)
curl -X GET 'https://easycms.fi/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=610910' \
-H 'Authorization1: TOKEN'

# Search CN codes by multiple keywords (AND logic)
curl -X GET 'https://easycms.fi/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=610910+cotton' \
-H 'Authorization1: TOKEN'

# Get only visible CN codes with pagination
curl -X GET 'https://easycms.fi/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&visible=1&start=0&limit=25' \
-H 'Authorization1: TOKEN'

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://easycms.fi/public_api/get_cn_codes?" . http_build_query([
    'username' => 'USERNAME', 
    'password' => 'PASSWORD', 
    'account' => 'ACCOUNT_ID',
    'search' => '610910'
  ]),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => array("Authorization1: TOKEN"),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

import requests

url = "https://easycms.fi/public_api/get_cn_codes"
headers = {"Authorization1": "TOKEN"}
params = {
    'username': 'USERNAME', 
    'password': 'PASSWORD', 
    'account': 'ACCOUNT_ID',
    'search': '610910'
}
response = requests.get(url, headers=headers, params=params)
print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://easycms.fi/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=610910"))
    .headers("Authorization1", "TOKEN")
    .GET()
    .build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const https = require('https');

const options = {
  hostname: 'easycms.fi',
  path: '/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=610910',
  method: 'GET',
  headers: {
    'Authorization1': 'TOKEN'
  }
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(data); });
});
req.on('error', (e) => { console.error(e); });
req.end();

import okhttp3.OkHttpClient
import okhttp3.Request

fun main() {
    val client = OkHttpClient()

    val request = Request.Builder()
        .url("https://easycms.fi/public_api/get_cn_codes?username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=610910")
        .addHeader("Authorization1", "TOKEN")
        .build()

    client.newCall(request).execute().use { response ->
        if (!response.isSuccessful) throw IOException("Unexpected code $response")
        println(response.body?.string())
    }
}




Handling Endpoint Results

When you make a request to the endpoint, you receive a JSON response containing various keys and values. Here's an explanation of the response keys and their meanings:


{
  "INFO": {
    "start": 0,
    "limit": 50,
    "count": 3,
    "total_count": 3
  },
  "OUTPUT": [
    {
      "cn_code_id": "1",
      "cn_codeNumber": "1",
      "cn_code_value": "555",
      "cn_code_name": {
        "fi": "555",
        "en_gb": "555",
        "zh": "555"
      },
      "parent_id": "0",
      "visible": "1"
    },
    {
      "cn_code_id": "2",
      "cn_codeNumber": "2",
      "cn_code_value": "610910",
      "cn_code_name": {
        "fi": "T-paidat, puuvilla",
        "en_gb": "T-shirts, cotton",
        "zh": "T恤, 棉"
      },
      "parent_id": "0",
      "visible": "1"
    },
    {
      "cn_code_id": "3",
      "cn_codeNumber": "3",
      "cn_code_value": "620342",
      "cn_code_name": {
        "fi": "Miesten housut, puuvilla",
        "en_gb": "Men's trousers, cotton",
        "zh": "男式长裤, 棉"
      },
      "parent_id": "2",
      "visible": "1"
    }
  ]
}
    

- `INFO`: Object containing pagination information
  - `start`: Starting index for pagination
  - `limit`: Maximum number of records returned
  - `count`: Number of records in this response
  - `total_count`: Total number of records available
- `OUTPUT`: Array of CN code objects
  - `cn_code_id`: Unique identifier for the CN code
  - `cn_codeNumber`: Numeric ordering identifier
  - `cn_code_value`: The CN code string value (e.g., "610910")
  - `cn_code_name`: Multilingual name object containing translations
    - `fi`: Name in Finnish
    - `en_gb`: Name in English
    - `zh`: Name in Chinese
    - (other language codes as configured)
  - `parent_id`: Parent CN code ID for hierarchical codes (0 = top-level)
  - `visible`: Visibility flag (1=visible, 0=hidden)
    

Error Handling

Here are the possible error messages and their meanings:

Error Code HTTP Status Description
Maximum query size is 50 rows per query 200 Exceeded maximum limit of 50 rows per query
UN-AUTHORIZED 401 Incorrect username or password
UN-AUTHORIZED - header is not set! 401 Authorization header is missing
UN-AUTHORIZED - header is set but the header value is not correct! 401 Incorrect authorization header value
UN-AUTHORIZED - _user_name_password_is_not_set! 401 Username or password not provided
UN-AUTHORIZED - _user_name_password_is_set_but_wrong_value! 401 Incorrect username or password
this_account_does_not_exist_or_your_credentials_do_not_match_this_account 401 The account doesn't exist or mismatched credentials

Related Endpoints