Chapter 1 of 12
Start with one real document
Use an actual invoice, claim or intake form. A made-up example hides the exceptions that should shape the model.
- 01
Name the record type
Use the business noun people already say: invoice, claim or supplier. Its lowercase code becomes part of the API coordinate.
- 02
Build the shape
Group fields into sections. Sections can nest and repeat, so model the document as it really reads instead of flattening it.
- 03
Preview and publish
Check the generated form and table, then publish an immutable version when the shape is ready for records and integrations.
Chapter 2 of 12
Know the five nouns
These terms appear in the interface, API coordinates and migration tools.
| Term | Meaning |
|---|---|
| Record type | A kind of thing you keep, such as an invoice or claim. |
| Schema | A named shape for that record type. |
| Section | A group of fields that can nest or repeat. |
| Version | An immutable published snapshot of a schema. |
| Draft | The one editable copy that has not been published. |
Chapter 3 of 12
Model your first record type
Describe structure, validation and presentation together so the API and working screens stay aligned.
- Use text, long text, whole number, decimal, true/false, date, date and time, time, or structured data for the stored value.
- Treat a choice as presentation, usually over a text field. Options can be fixed or read live from another record type, database or REST endpoint.
- Mark fields required, unique, searchable or indexed only when the business rule earns it.
- Use repeating sections for growing groups such as invoice lines; do not flatten them into numbered columns.
- Preview live choice sources before saving and use server-side search for long lists.
Chapter 4 of 12
Publish, then change safely
Publishing is the boundary: drafts can move; published versions stay fixed for records, integrations and running work.
- 01
Analyse
See whether a field addition, removal, type change or required-state change is breaking and whether stored rows need work.
- 02
Review the plan
Inspect the generated mapping and any conversion or transformation before it touches data.
- 03
Migrate
Run the plan. Rows that cannot convert are quarantined individually instead of stopping the whole migration or disappearing.
- 04
Archive
Retire the superseded version only after its records have moved. Archiving is refused when it would strand data.
Chapter 5 of 12
Use the generated API
Every published coordinate has the same list, record, bulk, schema and presentation surface, without generating or deploying code.
Signed-in Portal user
/v1/egav/portal/entity/{record_type}/attribute-set/{schema}/v{version}/flat/
External system with a Data API key
/v1/egav/client/entity/{record_type}/attribute-set/{schema}/v{version}/flat/| Operation | What it does |
|---|---|
| GET /flat/ | List with paging, filters, sorting and search. |
| POST /flat/ | Create one record against this version. |
| GET · PUT · DELETE /flat/{id} | Read, update or soft-delete one record. |
| POST · PUT · DELETE /flat/bulk | Process bounded batches. |
| GET /json-schema | Read the validation contract for this version. |
| GET /ui-schema | Read how its fields should be presented. |
| GET /flat/{id}/versions | List the record’s retained snapshots. |
| POST /flat/{id}/publish | Promote the working record when this schema uses controlled publishing. |
| GET /flat/{id}/published | Read the promoted snapshot, or 404 before the first promotion. |
Chapter 6 of 12
Choose the narrowest access tier
The record surface is repeated under four authentication boundaries. Pick the one that matches who is calling, not the easiest credential to obtain.
| Tier | Use it for |
|---|---|
| Portal | A signed-in person using your product. Their own session and permissions apply. |
| Client | A system you control calling with a scoped API key. |
| Internal | Service-to-service traffic inside the managed product environment. |
| Public | Anonymous reads only for a schema explicitly configured as public and live-on-save. Public writes are always refused. |
- Scope client keys to the record types the integration actually needs, then set per-minute and per-hour limits.
- Send both X-API-Key and X-App-Instance-Guid on Client-tier requests. The instance must match the one that issued the key.
- Rotation replaces the secret immediately. For a no-downtime cutover, mint a second key, deploy it, prove it, then revoke the first.
- Client-key callers always receive a published version, never the working draft.
- For a publish-enabled schema, Client reads return the promoted record snapshot. A newly created or updated working record stays invisible to Client reads until /publish succeeds.
- Public access is opt-in, live-on-save only and read-only. Anonymous create, update and delete requests are refused.
Chapter 7 of 12
Query, search and page through records
Lists are server-side operations. Send the page, filters and sort you need instead of downloading the full record set into a browser.
GET .../flat/?page=1&per_page=50&sort=-created_at
GET .../flat/?filters[status]=open&filters[amount][gte]=100
GET .../flat/?page=1&per_page=50&q=late+delivery&use_fts=true| Parameter | How to use it |
|---|---|
| page | One-based result page. |
| per_page | Rows per page, capped at 100. |
| filters | Use filters[field]=value or filters[field][operator]=value, such as gte or icontains. |
| sort | A field name; prefix with - for descending order. |
| q | A multi-column text match over searchable fields. |
| use_fts=true | Use the weighted full-text index for language-aware search. |
Chapter 8 of 12
Import, export and manage files
Use bounded bulk operations for application traffic, import/export for managed exchange, and signed links for file bytes.
- 01
Download the sample
Start from the CSV or JSON sample registered for the published version so column names and nested shapes match the contract.
- 02
Validate before committing
Review mapping and validation failures as data problems. Do not weaken the schema simply to make a dirty file pass.
- 03
Process bounded batches
Bulk create, update or delete through /flat/bulk. The whole insert counts against the row quota.
- 04
Change many records at once
On the record list, select the rows, choose Edit selected, pick the fields to change and set one value for each, then apply. Each value you set is written to every record you selected.
- 05
Export by version
Export the shape consumers expect and keep the schema version beside the file when it will be processed later.
| What a stopped edit reports | What it means for you |
|---|---|
| One of the values is not valid for its field. | A value you set does not fit the field you set it on. Correct it and apply again. |
| The edit conflicts with a constraint on these records. | The new value breaks a rule on the record type. One value written to many records collides with any field that has to stay unique. |
| The record type changed after this edit was queued. | The schema moved while the edit was waiting. Check the fields against the current published version, then apply again. |
| Waiting for a platform dependency to become available. | Nothing to do. The edit retries by itself. |
| The tenant database could not be reached, or did not respond in time. | Not something you can correct. The platform team is alerted; raise it with support if it keeps happening. |
- One request carries at most 200 records, and a larger selection is refused rather than quietly trimmed. Split a bigger job into several edits; separate edits are separate operations, not one.
- Fields that hold an uploaded file cannot be bulk edited. They stay visible in the picker but are disabled, with the reason shown: an upload is stored against a single record, so one file applied to many records has no defined meaning.
- System fields such as identifiers and the created and updated stamps are disabled in the same way. The platform maintains them, so they are never yours to set.
- Anyone allowed to edit a record is allowed to bulk edit. There is no separate permission for it, and a read-only member cannot use it.
- Every record the edit changes raises one record-updated event, so a workflow that listens for record updates runs once per record. A 200-record edit starts it 200 times.
Chapter 9 of 12
Keep history and control publishing
Turn on the controls that match the consequence of a change. Not every record needs approval, but important changes should be reconstructable.
- Record history keeps a snapshot per write to the retention depth you choose.
- Restore creates another recorded change; it never overwrites identifiers or audit columns.
- Controlled publishing can hold a record change until a scheduled time or an approval decision.
- Duplicate-detection rules and similarity thresholds are versioned with the schema that uses them.
- Full-text fields can carry different weights so a reference number outranks a note that merely mentions it.
- A high-volume schema can move to separately provisioned capacity without relocating every other record type.
Chapter 10 of 12
Send record changes outward
Subscribe per schema and push signed changes to HTTPS, Amazon SQS, Amazon SNS or Kafka instead of polling.
- Subscribe to created, updated, deleted, version-promoted and file-uploaded events.
- Verify every signature before acting and deduplicate on the event identifier.
- Use the field-level difference on updates when the receiver does not need to re-read the whole record.
- Expect at-least-once delivery: failures retry, then dead-letter with attempt history and bulk redrive.
- Use REST or bulk endpoints to send data in; queues and streams here are outbound destinations.
Chapter 11 of 12
Worked example: invoice records
Model one accounts-payable record, write it through the generated Client API and evolve the contract without silently changing existing consumers.
invoice_number text required · unique · searchable
supplier_code text required · searchable
total decimal required · minimum 0
currency text required · fixed choices: EUR, GBP, USD
status text required · fixed choices: received, approved, rejected, posted
due_date date required
lines repeating section
description text required
quantity decimal required · minimum 0
unit_price decimal required · minimum 0POST /v1/egav/client/entity/invoice/attribute-set/payables/v1/flat/
X-API-Key: <data-api-key>
X-App-Instance-Guid: <data-app-instance-guid>
Content-Type: application/json
{
"external_id": "erp-invoice-87421",
"invoice_number": "INV-87421",
"supplier_code": "SUP-1042",
"total": 1250.50,
"currency": "EUR",
"status": "received",
"due_date": "2026-08-31",
"lines": [
{"description": "Annual support", "quantity": 1, "unit_price": 1250.50}
]
}{
"data": [
{
"guid": "<invoice-record-guid>",
"external_id": "erp-invoice-87421",
"invoice_number": "INV-87421",
"status": "received",
"total": 1250.50
}
],
"meta": {"total": 1, "page": 1, "per_page": 10, "total_pages": 1},
"success": true,
"status": "success"
}- 01
Create a draft from v1
Keep v1 published and serving records while the next contract is edited.
- 02
Make the compatible change
Add purchase_order_number as optional. Existing rows and v1 callers remain valid.
- 03
Analyse and publish v2
Review the impact report, publish the immutable v2 contract and verify its generated form and JSON schema.
- 04
Move consumers deliberately
Migrate records when needed, inspect any quarantined rows, then change each consumer from /v1/ to /v2/. Publishing v2 does not rewrite a caller’s URL.
Chapter 12 of 12
Troubleshoot the common failures
Start with the product boundary most likely to explain the symptom before inspecting network traces or rewriting an integration.
| Symptom | Check first |
|---|---|
| A new field is missing from an integration | The field may exist only in the draft. Publish a version and confirm the consumer is using that coordinate. |
| A list or picker returns 422 or appears empty | Keep per_page at 100 or below and use the server-side search parameter for long lists. |
| A schema version cannot be archived | Records may still be pinned to it or rows may remain unmigrated. |
| A migration completed with fewer rows | Open the quarantine results; conversion failures are isolated per row. |
| The same webhook arrives twice | Delivery is at least once. Deduplicate on the event identifier before applying the change. |
| An anonymous write is rejected | The Public tier is read-only. Use a signed-in Portal call or a scoped Client key. |
| Search finds text but ranks it poorly | Check which fields are searchable, whether full-text search is enabled and how their weights are configured. |
Continue
See how the other product fits
Data and Automation are sold separately and work independently. Use both when a workflow should read or change a versioned business record.