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

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 such, we offer a dedicated endpoint expecting ndJSON (new-line-delimited JSON) as payload.

Endpoint

Depending on your organization's region, you will need to send your catalogs's 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

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 accepted format

When importing date-related properties, we only accept UTC ISO 8601 format, as following:

YYYY-MM-DDTHH:mm:ss.sssZ

Example valid value: 2025-11-16T04:25:03.000Z