API Guide

Definitions

These descriptions are designed to support correct usage of the API. For further assistance or questions, please submit a support ticket.

Name	Description	Required
solutionName	A unique identifier for the rollout or solution. Example: B2C_OOTB.	Yes
prefix	Optional prefix applied to all generated object names. Omit to use the raw schema names.	No
suffix	Optional suffix appended to all generated object names. Omit to use the raw schema names.	No
appName	The application for which the objects are being deployed.	Yes
appVersion	The semantic version of the application's standard schema being saved, rolled out, or upgraded.	Yes
objectName	The base object name. Exact object name matching is currently enforced during schema validation.	Yes
targetSchemaName	The schema within the data warehouse where the tables and data will be stored. Example: STAGE.	Yes
operationType	The type of ingest operation the API should perform. Supported values: UPSERT (insert or update based on primary key) or APPEND (insert only, similar to an insert operation).	Yes
dryRun	When true, the request runs the inline validation pipeline and the response is returned without writing any rows to the warehouse. See Validation behavior for what runs in dry-run mode. Default false.	No

API host and reference

All v2 endpoints share a single host. Use this base URL for every request in this guide:

https://ingestion.peak.ai

If your tenant is deployed in a regional cluster (a spoke deployment — used when data residency requirements apply to the tenant), the API is served from a cluster-specific host instead:

https://ingestion.<cluster-identifier>.peak.ai

For example, https://ingestion.peaksydney.peak.ai. Your account manager provides the cluster identifier for your tenant. Everything else in this guide works the same way — substitute your host wherever you see ingestion.peak.ai in the examples.

An interactive OpenAPI / Swagger reference is served at the same host:

https://ingestion.peak.ai/api-docs/

The Swagger page lists every endpoint, request schema, and response schema and lets you try requests inline. Use it as the source of truth when generating client code or validating a payload structure.

Operation types

The API supports two operation types — UPSERT and APPEND. The right choice depends on what the downstream solution needs from the data: only the current state of each record, or the full history of how it evolved over time.

UPSERT

• Behavior: insert new records, or update existing records by primary key.
• Use when: downstream only cares about the current state of each record. Re-submitting a row with the same primary key overwrites the previous version in place.

APPEND

• Behavior: insert only. Does not update existing records.
• Use when: downstream needs every version of every record — for time-series analysis, audit, or model features that depend on historical state. Tables designed for APPEND typically include a temporal field (for example UPDATED_AT or SOLD_AT) in the primary key, so successive versions of the same logical entity become distinct rows.

Choosing the right operation per table

The choice is per-table, not per-data-type. The same kind of data can need different operations in different solutions:

• A reporting dashboard that only needs today's customer attributes → UPSERT on the customer table.
• A pricing or recommendation model that uses how each customer's attributes evolved over time as features → APPEND on the customer table.

The solution-specific guides (such as Commercial Pricing) state the recommended operation per table where it matters. Use those as your starting point.

The operationType you submit is recorded as "upsert" or "append" on each failed row in the <table_name>_failed_rows companion table — see Audit columns added at rollout for the full list of columns the API populates automatically.

Validation behavior

Validation runs in two stages:

• Inline (synchronous), before the API responds — three classes of check run on every row:

  • Schema checks — column exists in the schema, types match, required fields are present.
  • Data-format and type validation — date / timestamp / numeric / boolean parse, range, length, enum membership, precision and scale.
  • Intra-payload deduplication — duplicate or null primary keys, duplicate unique keys within the same request.

  Rows that fail any of these are returned in the response's failed array and recorded to the matching <table_name>_failed_rows companion table for triage in the Data Quality Dashboard.

• Asynchronous, after the response — cross-dataset checks that need the warehouse state: foreign-key references to rows in other tables, and primary-key / unique-key collisions against rows already persisted. Failures from this stage do not appear in the original response; they are recorded to <table_name>_failed_rows and surface in the Data Quality Dashboard.

A 200 OK response means every row in the request passed inline validation and was accepted for ingestion. It does not mean the rows are queryable yet, or that they have passed the asynchronous checks.

When dryRun: true, the request runs the full inline validation pipeline above but no rows are written to the warehouse — so asynchronous validation does not run either. Use it to catch schema, type, and format errors before submitting a real batch.

Scheduled ingestion

Every table runs on scheduled ingestion: rows are buffered per table and flushed to the warehouse on a cron schedule (every 30 minutes by default). See Scheduled ingestion for the cron format and how to customize the schedule per table.

API limits

The API supports ingestion of up to 2000 rows per request, with a maximum payload size of 1 MB. When ingesting larger datasets, ensure your data is split into appropriately sized batches. Rate limits are 50 requests per second per tenant.

For deletion, each request can target between 1 and 500 primary key value sets.

Response status codes

The ingest endpoint uses three status codes to communicate the outcome of a batch:

Status	Meaning
200 OK	Every row in the request passed validation and was accepted.
207 Multi-Status	Some rows passed and some failed. Successful rows are accepted; failed rows are returned in the response's failed array with structured error details.
400 Bad Request	Every row in the request failed validation, or the request payload itself is malformed.

Other endpoints return standard HTTP semantics: 201 Created for successful schema saves and rollouts, 404 Not Found when a referenced solution or schema does not exist, 409 Conflict when saving a duplicate appName + appVersion, and 500 Internal Server Error for unexpected failures.

Error codes

Each validation failure returns a structured error response containing an error code, category, and message. Codes follow the pattern DI_E_XXXXX (errors) or DI_W_XXXXX (warnings, non-fatal).

Resolution guidance by category

Category	What It Means	Consumer Action
BUSINESS_VALIDATION	Data value violates a schema-defined business rule	Fix the data value (correct format, valid enum, within range, etc.)
SYSTEM_DATA	Data integrity issue (missing PK, duplicate, null PK, type mismatch)	Fix the data (provide PK, remove duplicates, fill required keys, send the right JSON type)
SYSTEM_SCHEMA	Data structure does not match the schema definition	Fix the schema/data alignment (column not in schema, PK column missing, precision/scale mismatch)

Business-level validation errors — Category: BUSINESS_VALIDATION

These come from schema-defined validation rules configured per attribute (required, range, enum, length, date/timestamp format).

#	Error Code	When Triggered	Standard Message
1	DI_E_23N01	required validator: field absent from payload	Required field is absent
2	DI_E_23502	nonNull validator: value is null	Value cannot be null
3	DI_E_23E01	nonNull validator: string is blank/empty	String value cannot be empty
4	DI_E_22026	minLength validator: string too short	String length is below minimum
5	DI_E_22001	maxLength validator: string too long	String length exceeds maximum
6	DI_E_22003	range validator: value above max or below min	Numeric value out of allowed range
7	DI_E_22P02	range validator: value not numeric	Value is not a valid number
8	DI_E_22023	enum validator: value not in allowed set	Value is not one of the allowed enum values
9	DI_E_22007	dateTimeFormat validator: unparseable date	Invalid date format
10	DI_E_22008	timestampFormat validator: unparseable timestamp or negative epoch	Invalid timestamp format or epoch

System-level data validation errors — Category: SYSTEM_DATA

These come from data integrity checks (primary key null, duplicate, type mismatch) and unique key checks.

#	Error Code	When Triggered	Standard Message
11	DI_E_23P01	PK attribute value is null/empty in a row	Primary key value cannot be null/empty
12	DI_E_23505	2+ rows in same batch share a PK value	Duplicate primary key
13	DI_E_23U01	2+ rows in same batch share a unique-key value	Duplicate unique key
14	DI_E_22I01	Value not parseable as integer	Value is not a valid integer
15	DI_E_22N01	Value not parseable as number/float	Value is not a valid number
16	DI_E_22B01	Value not parseable as boolean	Value is not a valid boolean
17	DI_E_22S02	Value not a valid string	Value is not a valid string
18	DI_E_22T01	Timestamp field is empty string	Timestamp value is empty
19	DI_E_22P03	Empty/null value during precision/scale check	Precision/scale field is empty or null
20	DI_E_22P04	Precision/scale validation error	Precision/scale validation error

System-level schema validation errors — Category: SYSTEM_SCHEMA

These come from data type mismatches and schema structural checks.

#	Error Code	When Triggered	Standard Message
21	DI_E_42703	Attribute in data row not found in schema	Column not found in schema
22	DI_E_23P02	PK attribute entirely absent from a row	Primary key column is missing
23	DI_E_22T02	Timestamp field is wrong JSON type	Timestamp value has wrong type
24	DI_E_22P01	Total digits exceed attribute precision	Numeric value exceeds allowed precision
25	DI_E_22S01	Decimal digits exceed attribute scale	Numeric value exceeds allowed scale

Quick reference — all codes sorted

Code	Category	Short Description
DI_E_22001	BUSINESS_VALIDATION	String too long (max length)
DI_E_22003	BUSINESS_VALIDATION	Numeric out of range (min/max)
DI_E_22007	BUSINESS_VALIDATION	Invalid date format
DI_E_22008	BUSINESS_VALIDATION	Invalid timestamp format / invalid epoch
DI_E_22023	BUSINESS_VALIDATION	Invalid enum value
DI_E_22026	BUSINESS_VALIDATION	String too short (min length)
DI_E_22B01	SYSTEM_DATA	Invalid boolean type
DI_E_22I01	SYSTEM_DATA	Invalid integer type
DI_E_22N01	SYSTEM_DATA	Invalid number type
DI_E_22P01	SYSTEM_SCHEMA	Numeric precision exceeded
DI_E_22P02	BUSINESS_VALIDATION	Value is not a valid number
DI_E_22P03	SYSTEM_DATA	Empty value for precision/scale check
DI_E_22P04	SYSTEM_DATA	Precision/scale validation error
DI_E_22S01	SYSTEM_SCHEMA	Numeric scale exceeded
DI_E_22S02	SYSTEM_DATA	Invalid string type
DI_E_22T01	SYSTEM_DATA	Timestamp empty string
DI_E_22T02	SYSTEM_SCHEMA	Timestamp wrong JSON type
DI_E_23502	BUSINESS_VALIDATION	Not-null violation
DI_E_23505	SYSTEM_DATA	Duplicate primary key in batch
DI_E_23E01	BUSINESS_VALIDATION	Not-empty violation
DI_E_23N01	BUSINESS_VALIDATION	Required field missing
DI_E_23P01	SYSTEM_DATA	Primary key value is null/empty
DI_E_23P02	SYSTEM_SCHEMA	Primary key column missing from row
DI_E_23U01	SYSTEM_DATA	Duplicate unique key in batch
DI_E_42703	SYSTEM_SCHEMA	Column not found in schema

Categorization logic

Use the error code prefix to quickly identify the class of error:

DI_E_22XXX  →  Data exception      (type/format/range/precision)
DI_E_23XXX  →  Integrity constraint (null/unique/pk/required)
DI_E_42XXX  →  Schema mismatch     (undefined columns)
DI_W_XXXXX  →  Warning             (non-fatal, future use)