Schema detection & field mapping
Requires the Grow plan or higher.
After you connect your API in Connecting a catalog, the wizard walks you through telling Promptly what your fields mean. This is steps 2 and 3 of the setup wizard.
Step 2 — Detect Schema (Review Fields)
When detection finishes, the wizard lists every field it found from a sample product, grouped into two sections:
- Important fields — fields the AI flagged as useful for search or filtering.
- Other detected fields — the rest, collapsed by default. Expand to promote any you need.
For each field you can set:
- Display Name — the human label.
- Type — string, number, or boolean.
- Searchable — include the field in semantic (text) search.
- Filterable — allow exact, range, or contains filters on it. Choose the Filter Type when filterable.
Use the up/down chevrons to move a field between Important and Other, the trash icon to remove it, and Add Field to register a field detection missed. Click Next to continue to mapping.
🖼️ [Image] — Step 2 with Important and Other field sections and the searchable/filterable toggles
Step 3 — Mapping
The Field Mapping sub-tab shows how each API field maps to a Promptly product field — title, description, price, image, url, id, and others. The AI pre-fills these from detection; verify and correct them. A field mapped to Ignored is stored but not used by the bot.
Open the Test Preview sub-tab to see how a real product looks once mapped, so you can catch a wrong price or image path before saving.
Pagination
Tell Promptly how to page through your full catalog (the AI suggests this from detection when it can):
| Type | Use when |
|---|---|
| None | The API returns everything in one response. |
| Page-based | Numbered pages — set the page and limit params and page size. |
| Cursor-based | A cursor token points to the next page — set the cursor param and path. |
| Link Header | Next-page URL comes in the HTTP text |
You can also cap the maximum number of products imported.
Step 4 — Test & Save
On the final step, enter a search term and click Test Search to run a live query against your API and preview the returned products. When the results look right, click Save & Activate. Promptly persists your schema, generates a product search tool for the bot, and marks the catalog ready to sync.
🎬 [Video] — Mapping fields, previewing a product, then running Test Search and activating
Your wizard progress is saved as you advance, so you can leave and resume later. Next, run your first import in Sync & scheduling.