Industry & Department Solutions

industry-department-solutions

latest

false

Supply Chain & Retail Solutions API guide

Customizations

Extend standard Data Ingestion API schemas by adding custom attributes to any API object for business-specific fields and metadata.

The Data Ingestion API supports adding custom attributes to existing APIs, allowing you to send additional information specific to your business requirements.

Overview

Custom attributes provide a way to:

Extend standard schemas – add business-specific fields to any object without modifying the base schema
Maintain flexibility – adapt to changing data requirements without engineering intervention
Preserve validation – custom attributes are validated according to their defined data types and constraints

Workflow

The process for using custom attributes involves three steps:

Add custom attributes – define additional columns using the /api/v2/schema/{objectName}/add-attribute endpoint with UPPERCASE column names
Retrieve updated schema – fetch the schema using /api/v2/schema?solutionName={solutionName} to confirm the custom columns (optional)
Ingest data – submit data including the custom columns via the standard ingestion endpoint using the pattern /api/v2/objects/{prefix}{object_name}{suffix}

Adding custom attributes

Use the POST /api/v2/schema/{objectName}/add-attribute endpoint to add custom columns to an existing object schema.

Request parameters

Parameter	Type	Required	Description
`solutionName`	string	Yes	A unique identifier for the rollout or solution. (e.g., `QP_OOTB`)
`columnName`	string	Yes	The name of the custom column in UPPERCASE (e.g., `SUPPLIER_CODE`)
`dataType`	string	Yes	Data type: `string`, `integer`, `float`, `boolean`, `datetime`, `date`
`defaultValue`	string	No	Default value for the column
`validations`	array	No	Array of validation rules (e.g., `nonNull`, `minLength`, `maxLength`)

Step 1: Add custom attribute

curl -X POST \
  'https://ingestion.peak.ai/api/v2/schema/PRODUCTS/add-attribute' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "columnName": "SUPPLIER_CODE",
    "dataType": "string",
    "defaultValue": "21C",
    "validations": [
      {
        "type": "nonNull"
      },
      {
        "type": "minLength",
        "value": 3
      },
      {
        "type": "maxLength",
        "value": 100
      }
    ]
  }'
curl -X POST \
  'https://ingestion.peak.ai/api/v2/schema/PRODUCTS/add-attribute' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "columnName": "SUPPLIER_CODE",
    "dataType": "string",
    "defaultValue": "21C",
    "validations": [
      {
        "type": "nonNull"
      },
      {
        "type": "minLength",
        "value": 3
      },
      {
        "type": "maxLength",
        "value": 100
      }
    ]
  }'

Success Response

{
  "message": "Custom attribute added successfully"
}
{
  "message": "Custom attribute added successfully"
}

The new column is now part of the schema. When ingesting data, use the exact column name you specified above as the JSON key — for example, "SUPPLIER_CODE": "SUP-XYZ-001".

Step 2: Retrieve updated schema (optional)

curl -X GET \
  'https://ingestion.peak.ai/api/v2/schema?solutionName=QP_OOTB' \
  -H 'Authorization: YOUR_API_KEY'
curl -X GET \
  'https://ingestion.peak.ai/api/v2/schema?solutionName=QP_OOTB' \
  -H 'Authorization: YOUR_API_KEY'

Response

{
  "solutionName": "pricing-b2b",
  "appName": "pricingb2b",
  "appVersion": "v1.0.0",
  "targetSchema": "stage",
  "prefix": "test_",
  "suffix": null,
  "createdAt": "2026-01-20T09:06:15.891Z",
  "schema": [
    {
      "objectName": "QP_PRODUCTS_OOTB",
      "primaryKeys": [
        "PRODUCT_ID",
        "UPDATED_AT"
      ],
      "columns": [
        {
          "columnName": "PRODUCT_ID",
          "dataType": "string",
          "validations": []
        },
        {
          "columnName": "PRODUCT_NAME",
          "dataType": "string",
          "validations": []
        },
        {
          "columnName": "SUPPLIER_CODE",
          "dataType": "string",
          "validations": [
            {
              "type": "nonNull"
            },
            {
              "type": "minLength",
              "value": 3
            },
            {
              "type": "maxLength",
              "value": 100
            }
          ]
        }
      ],
      "isRolledOut": true
    }
  ]
}
{
  "solutionName": "pricing-b2b",
  "appName": "pricingb2b",
  "appVersion": "v1.0.0",
  "targetSchema": "stage",
  "prefix": "test_",
  "suffix": null,
  "createdAt": "2026-01-20T09:06:15.891Z",
  "schema": [
    {
      "objectName": "QP_PRODUCTS_OOTB",
      "primaryKeys": [
        "PRODUCT_ID",
        "UPDATED_AT"
      ],
      "columns": [
        {
          "columnName": "PRODUCT_ID",
          "dataType": "string",
          "validations": []
        },
        {
          "columnName": "PRODUCT_NAME",
          "dataType": "string",
          "validations": []
        },
        {
          "columnName": "SUPPLIER_CODE",
          "dataType": "string",
          "validations": [
            {
              "type": "nonNull"
            },
            {
              "type": "minLength",
              "value": 3
            },
            {
              "type": "maxLength",
              "value": 100
            }
          ]
        }
      ],
      "isRolledOut": true
    }
  ]
}

Step 3: Ingest data with custom attributes

curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_PRODUCTS_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "data": [
      {
        "PRODUCT_ID": "PROD-001",
        "NAME": "Premium Widget",
        "DESCRIPTION": "High-quality widget with extended warranty",
        "LOWEST_PRODUCT_CATEGORY_ID": "CAT-100",
        "CREATED_AT": "2024-01-15 10:30:00",
        "UPDATED_AT": "2024-01-15 10:30:00",
        "SUPPLIER_CODE": "SUP-XYZ-001"
      }
    ],
    "operationType": "UPSERT"
  }'
curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_PRODUCTS_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "data": [
      {
        "PRODUCT_ID": "PROD-001",
        "NAME": "Premium Widget",
        "DESCRIPTION": "High-quality widget with extended warranty",
        "LOWEST_PRODUCT_CATEGORY_ID": "CAT-100",
        "CREATED_AT": "2024-01-15 10:30:00",
        "UPDATED_AT": "2024-01-15 10:30:00",
        "SUPPLIER_CODE": "SUP-XYZ-001"
      }
    ],
    "operationType": "UPSERT"
  }'

Success Response

{
  "message": "Data ingested successfully",
  "recordsProcessed": 1
}
{
  "message": "Data ingested successfully",
  "recordsProcessed": 1
}

Important considerations

Data type mapping

Custom attributes support the following data types:

Data Type	Description	Example Values
`string`	Variable-length string	`"ABC123"`, `"Product Code"`
`integer`	Whole numbers	`42`, `-10`, `0`
`float`	Decimal numbers	`19.99`, `-0.5`, `3.14159`
`boolean`	True/false values	`true`, `false`
`datetime`	Timestamp with time	`"2025-01-23T14:30:00Z"`
`date`	Date only	`"2025-01-23"`

Validations

Custom attributes support validation rules to enforce data quality:

Validation Type	Description	Example
`nonNull`	Field cannot be null or empty	`{"type": "nonNull"}`
`minLength`	Minimum string length	`{"type": "minLength", "value": 3}`
`maxLength`	Maximum string length	`{"type": "maxLength", "value": 100}`
`min`	Minimum numeric value	`{"type": "min", "value": 0}`
`max`	Maximum numeric value	`{"type": "max", "value": 1000}`

Schema evolution

Custom attributes are additive – they extend the schema without affecting existing attributes
Once added, custom attributes become part of the schema and are subject to the same validation rules as standard attributes
Removing custom attributes requires submitting a support ticket

Validation

Custom attributes with nonNull validation must be present in all ingested rows
Data types are strictly validated – sending an incorrect type will result in a validation error
Custom attributes with default values will use the default if the field is omitted from the data payload
Multiple validations can be applied to a single attribute (e.g., nonNull, minLength, and maxLength together)

For further assistance with custom attributes or schema customization, submit a support ticket.

Was this page helpful?

PREVIOUSData Quality Dashboard

NEXTData Onboarding Checklist

Overview​

Workflow​

Adding custom attributes​

Request parameters​

Step 1: Add custom attribute​

Success Response​

Step 2: Retrieve updated schema (optional)​

Response​

Step 3: Ingest data with custom attributes​

Success Response​

Important considerations​

Data type mapping​

Validations​

Schema evolution​

Validation​

Was this page helpful?

Overview

Workflow

Adding custom attributes

Request parameters

Step 1: Add custom attribute

Success Response

Step 2: Retrieve updated schema (optional)

Response

Step 3: Ingest data with custom attributes

Success Response

Important considerations

Data type mapping

Validations

Schema evolution

Validation