Catalogs data

You can find detailed information about how catalogs work in our Help center.

Import single catalog line

Endpoint

Depending on your organization's region, you will need to send your catalog's data to the corresponding endpoint:

• EU: POST https://analytics-api-eu.piano.io/import/v1/catalogs
• US: POST https://analytics-api-us.piano.io/import/v1/catalogs
• AP: POST https://analytics-api-ap.piano.io/import/v1/catalogs

Headers

Authentication

• header name: x-api-key
• header value: an API key from your profile in the solution with the following pattern: <ACCESSKEY>_<SECRETKEY>

Content-Type

• header name: Content-Type
• header value: application/json

Payload

The expected payload is JSON object, following the schema below:

{
  "import_id": "<IMPORT_ID>",
  "import_keys": {
    "key1": "val1"
  },
  "associated_properties": {
    "prop1": "prop1"
  }
}

Parameters

Parameter	Mandatory?	Type	Comment
import_id	YES	string	Catalog ID, you can retrieve it in your Data Management interface
import_keys	YES	object	List of catalog keys and value to import
associated_properties	YES	object	List of catalog data to import

tip

You can find a catalog import example in your Data Management interface.

Limits

Feature	Limit
JSON max body size	100KB

Import multiple catalog lines

In order to import multiple catalog lines, you can use a batch request. To do so, we offer a dedicated endpoint expecting ndJSON (newline-delimited JSON) as payload.

Endpoint

Depending on your organization's region, you will need to send your catalogs' data to the corresponding endpoint:

• EU: POST https://analytics-api-eu.piano.io/import/v1/catalogs/batch
• US: POST https://analytics-api-us.piano.io/import/v1/catalogs/batch
• AP: POST https://analytics-api-ap.piano.io/import/v1/catalogs/batch

Headers

Authentication

• header name: x-api-key
• header value: an API key from your profile in the solution with the following pattern: <ACCESSKEY>_<SECRETKEY>

Content-Type

• header name: Content-Type
• header value: application/x-ndjson

Payload

The expected payload is one-line JSON object per import to proceed, following the schema below:

{"import_id": "<IMPORT_ID>","import_keys":{"key1": "val1"},"associated_properties":{"prop1": "prop1"}}
{"import_id": "<IMPORT_ID>","import_keys":{"key1": "val2"},"associated_properties":{"prop1": "prop2"}}
{"import_id": "<IMPORT_ID>","import_keys":{"key1": "val3"},"associated_properties":{"prop1": "prop3"}}
{"import_id": "<IMPORT_ID>","import_keys":{"key1": "val4"},"associated_properties":{"prop1": "prop4"}}

Parameters

Parameter	Mandatory?	Type	Comment
import_id	YES	string	Catalog ID, you can retrieve it in your Data Management interface
import_keys	YES	object	List of catalog keys and value to import
associated_properties	YES	object	List of catalog data to import

tip

You can find a catalog import example in your Data Management interface.

Limits

Feature	Limit
ndJSON max body size	1GB
ndJSON max line size	100KB

Date properties

CSV catalog imports (manual upload and sFTP) do not support time zones. Send the value in UTC, with a Z suffix:

YYYY-MM-DDTHH:mm:ssZ

Example: 2026-10-09T15:11:00+09:00 is 2026-10-09T06:11:00Z.

An offset such as +09:00 is rejected. Convert the instant to UTC before import. Removing the offset and keeping the same clock time stores a different moment.

A value collected by the SDK can include an offset. That processing does not apply to a CSV catalog import.