Parameter Introduction

Latest Update Time: 2026-07-02 00:00:00

The Parameter module provides QIMA's common reference data: geographic data (continents, countries, provinces, cities) and product taxonomy data (categories, families, types, sample levels). Use these APIs to populate dropdowns and to obtain valid ID values required by other modules — for example, supplierContinentID/supplierCountryID/supplierCityID when creating an Inspection or Audit order, or product line values for a supplier.

This page documents the shared setup used by every Parameter guide. Each API-specific guide links back here for authentication, headers, and environment details.

Base URL

All Parameter APIs are served from the QIMA Public API host for your environment:

https://ppapi.qima.com

For production integrations, replace the host with the QIMA API host provided for your environment.

Required Headers

Call the Auth API first (POST /auth/v2/token) before any Parameter request. See the Getting Started Guide or Get Token API for authentication setup.

Header	Location	Source	Description
`Ai-Api-Access-Token`	Request header (all Parameter APIs)	Provided by QIMA	Request source identifier. Each client may have a different value per environment.
`Ai-User-Id`	Request header (all Parameter APIs)	Auth API response `userId`	QIMA client user login ID of the authenticated user.
`Authorization`	Request header (all Parameter APIs)	Auth API access token	Format: `Bearer <access-token>`. Use the token from the same Auth API session as the other headers.
`Referer`	Request header (all Parameter APIs)	Fixed value	`https://preprodmy.qima.com/`

Common Authentication Errors

Status	Meaning	Recommended Action
`401 Unauthorized`	Token or user authentication failed.	Confirm the `Authorization`, `Ai-User-Id`, and `Ai-Api-Access-Token` headers are from the same Auth API session and environment.
`403 Forbidden`	The user does not have access to the requested resource.	Verify account permissions.

Common Response Shape

Every Parameter API wraps its data in the same envelope:

{
  "message": null,
  "content": "... the actual data, shape varies per API ..."
}

message is usually null on success (some endpoints return "OK" instead — treat both as success). Most geography endpoints also accept a refresh query parameter: send false (default) to use QIMA's server-side cache, or true to force a fresh lookup.

Available APIs

Geographic Data

API	Method	Endpoint	Guide
Get all continents	`GET`	`/parameter/v2/continents`	Guide
Get countries by continent	`GET`	`/parameter/v2/continent/{continentId}/countries`	Guide
Get all countries	`GET`	`/parameter/v2/countries`	Guide
Search countries by name	`GET`	`/parameter/v2/searchCountries`	Guide
Get provinces by country	`GET`	`/parameter/v2/country/{countryId}/provinces`	Guide
Get cities by country	`GET`	`/parameter/v2/country/{countryId}/cities`	Guide
Search cities in a country by name	`GET`	`/parameter/v2/country/{countryId}/searchCities`	Guide
Search cities in a province by name	`GET`	`/parameter/v2/province/{provinceId}/searchCities`	Guide

Product Taxonomy & Sample Levels

API	Method	Endpoint	Guide
Get all product categories	`GET`	`/parameter/v2/product-categories`	Guide
Get all product families	`GET`	`/parameter/v2/product-families`	Guide
Get all product types	`GET`	`/parameter/v2/product-types`	Guide
Get full product taxonomy tree	`GET`	`/parameter/v2/product-tree`	Guide
Get the lists of available sample levels	`GET`	`/parameter/v2/sample-levels`	Guide

Integration Workflows

1. Authenticate (Required for All Flows)

2. Build a Location Picker (Continent → Country → Province/City)

Use Search Countries, Search Cities in a Country, or Search Cities in a Province instead of the full list APIs when building an autocomplete/typeahead field.

3. Get Product Taxonomy Values for a Booking

Use these APIs to obtain valid categoryId/familyId/typeId values (and supplier/factory ProductLines) before creating an Inspection, Audit, or Supplier record.

/parameter/v2/product-tree returns everything in a single call; the individual category/family/type APIs are useful when you only need one level, or want to keep payloads smaller.

Choosing the Right API

Your goal	Recommended APIs
Populate a continent/country/province/city dropdown	The relevant "Get ... by ..." API
Autocomplete a country or city as the user types	Search Countries, Search Cities in a Country, Search Cities in a Province
Get valid product category/family/type IDs for a booking	Product Tree (all at once) or the individual category/family/type APIs
Get valid sample level values for a lab testing/inspection checklist	Sample Levels

Getting Started Guide — Authentication and first API call
Module Overview — Overview of all QIMA Public API modules
API Reference — Interactive endpoint explorer for all Public APIs

Documents