Form, field and widget tools

For: developers connecting an HTTP or MCP client. Start with Agent API and AI clients.

AI is optional. You confirm invoice issuance in Pepper.

Forms and custom fields

These tools need the delegate's Use internal forms permission and current record access.

forms_get needs id and type (form, form_record or form_submission). Only form managers receive the public form address.

Custom reads need type, the registered record type. Value and merge reads also need id. Merge needs template, up to 4,000 characters.

fields_schema returns active definitions. Use custom_<key> in ordinary view filters, sorts and columns. Retired or unsupported criteria return 422.

forms_prepare needs operation, payload and an idempotency key. HTTP uses the Idempotency-Key header; MCP uses idempotency_key.

Preparation returns written: false, proposed input and review_url. It writes no form, customer, custom value, file or submission.

Open the link in the browser. Review the proposed values or the submission's current state. Use the ordinary Save, Publish form, Submit form, Retire field, Archive or Restore control.

Publish and retire links open the appropriate screen without selecting or executing the action. Check the intended field and state yourself.

Archive and restore links open the permitted submission. The page shows its current state and the available control; opening it changes nothing. Preparation returns no proposed values for these operations. Form management and current record access still apply when you open the link and confirm the action.

The browser rechecks permissions and versions. Prepared input has a 12,000-byte limit. Choose new files in the browser.

Read the forms manual for the complete definition and value limits. Public links are separate from agent connections.

Submit forms and change custom fields

These tools make the changes a person makes on internal forms and custom fields, as that person and through the same action as Pepper. Each write needs an idempotency key and appears in the record's activity as done by an AI connection for that person.

forms_submit needs the form's current version; a submission to an older version is refused. A form that creates or changes a customer returns 409 approval_required to an AI client; use customers_create or customers_update and wait for approval. fields_set needs the revision that fields_get returned. Field definitions for a board's cards need board admin; record fields need Manage forms. A retired field keeps its stored values in history and exports.

Widgets

The delegate must be active and not a guest. Each type applies the same permission as its screen. Common types are listed below.

A people manager may close another person's card in Pepper. That does not grant the agent read or prepare access to it.

widgets_get needs id. It returns configuration, page address, website code, counts and permitted editor choices. It returns no visitor identity.

widgets_requests_get returns one request within the delegate's access, including its contact details and requested items. It grants no access to the linked lead.

Save a widget or placement

widgets_save makes the same reversible save as the native configurator. Send payload_json, a JSON string containing the complete widget definition.

For an edit, include widget_id, the current definition version and the current source.version when changing source settings.

Use the Idempotency-Key header for HTTP or idempotency_key for MCP. A repeated accepted request returns its existing record; changed input cannot reuse its key.

The receipt returns widget and source IDs and versions. It contains no browser handoff and makes no publication claim. Saving closes existing publication.

Read widgets_get for permitted source choices. A shop uses currency_code, tax_source (catalogue or rules), items, shipping_method_ids and booking_widgets.

A buy button uses shop_widget_id and item_id. It references a published shop; it cannot supply its own price, seller or order engine.

widgets_catalogue returns that widget's current public catalogue as content_json. It reveals no visitor identity, private download identifier or exact internal stock quantity.

widgets_placements_save needs widget_id and payload with name, channel and destination_id. print_quantity is optional.

For an edit, add placement_id and current payload.version. The destination must be a published widget within the delegate's current access.

These writes need no sensitive-action approval. Publication and placement closure retain their separate exact approvals. Permission loss also blocks retained receipt reads and downloads.

Shop management does not require unrelated form management. Each call checks the widget type's actual native permissions and current source access.

Payment credentials, visitor email verification, consent and checkout remain with their permitted human actors. These tools do not act as a visitor.

Read shop setup for the complete customer journey. Get the exact current schemas through GET /api/v1/tools or MCP tools/list.

Prepare a widget

widgets_prepare needs payload and an idempotency key. HTTP uses Idempotency-Key; MCP uses idempotency_key.

For an edit, send widget_id. A source edit includes its current source.version.

Card settings are show_photo, show_title, show_phone and show_email. The server derives the owner and public profile values.

Team settings contain title and an ordered cards array of published card-source IDs. Price-list settings contain title, selected items IDs and include_tax.

The result contains written: false, payload and review_url. Open the link, review the preview and save through the ordinary configurator.

Saving closes publication. Enable and publish through the browser after checking the content and website origins. Preparation performs no save or publication action.

The browser proposal has a 12,000-byte limit. Form sources may target response records, leads or board cards, without linked-record fields.

Prepare a placement

Send widget_id, payload and an idempotency key. For an edit, include placement_id and the current payload.version.

The payload contains name, channel and destination_id. The channel is print, online, email or messaging.

print_quantity is optional. The destination must be a published widget within the delegate's access.

Preparation returns written: false, proposed values and review_url. Review them in Reusable links & QR codes, then click Create code or Save code.

widgets_prepare and widgets_placements_prepare remain proposal-only tools. Use their browser handoff when you want to finish configuration there, or use the save tools above.

After your exact approval, widgets_publish can publish or withdraw a widget, and widgets_placement_close can close a placement. Read Approve sensitive steps for the approval process. Visitor submissions stay human-only. Read the widget guide for publication and print instructions.

Preview, list and print widgets

A placement print file opens once through a download link valid for five minutes. See Upload and download files.

Read widget analytics

analytics_read, HTTP GET /api/v1/analytics and Customer services > Analytics use the same report. It covers websites, shops and widgets with the same calculations, permissions and privacy limits.

The client needs analytics:read and the delegated person's View analytics permission. Exact results also require access to their source records. Website and shop sections serve installation staff; customer workspaces retain their own widget reports. The shop section requires View all orders and a readable shop.

Use from and to in YYYY-MM-DD format. Dates use the business timezone and include both endpoints, up to 366 days. Without dates, the report covers this month through today. The response includes the previous period of equal length.

site_page and locale require site_id. Use site_id for Pepper websites; website_id identifies an external website registered for widget measurement.

The websites, shop and item_insights fields use these filters. Website traffic never increases widget counts. A currency filter withholds shop request counts because requests have no currency.

Country, device and arrival filters cannot link anonymous requests to exact records. A website arrival-source filter also withholds those records unless an approved campaign supplies the stored link.

Counted breakdowns hide groups of 1–4 and other values that could reveal them by subtraction. Keep missing or null figures unavailable. If expired checkout details prevent product filtering, the report withholds that funnel instead of returning zero.

The response carries the same sections as the screen: websites, shop, revenue, placement_sets, agents and the widget sections. A section's answer holds the answer sentence as sentence parts. It can add one next action with key, label_key, values, href, permission and dismiss_key; the client receives it only when the person may open that link. overview_answer and placement_answer hold the Overview and register sentences. placement_paid holds the paid total across the listed sets per currency, in exact minor units, as the register shows it. previous holds the previous period. A withheld figure is null; never read it as zero.

filter_dimensions names the breakdowns that have more than one value in this period. Send one of them back as a filter to look closer. includes_today is true when the period contains today; only such a period can still change. has_any_placement is false before the business places its first widget, website or campaign.

Visitor agent calls stay in agents. They never add to page views, widget views or arrivals. Filters that agent calls do not carry, such as campaign_id, set_id, locale or country, make the agent figures unavailable. A site_id or site_page filter keeps only website page reads.

The revenue result separates last and first attribution models. It returns signed minor-unit strings with their currency and scale. Monetary fields require See balances and figures and ordinary document access. Keep currencies separate and preserve exact strings.

Several screens use the same last-30-day report with their own filters. These are the Websites list, editor Insights, the product page, QR figures in the publishing kit, Cards at work and the Reach instrument. Their links retain those dates and filters.

analytics_prepare prepares settings, a widget goal or a count target for browser review. It needs Configure analytics and writes nothing. Pass operation as settings, goals or targets, the corresponding payload, and an idempotency_key. Targets also need goal_id. Open the returned review URL, check the fields and save each change. The tool cannot enable collection by itself.

Write a report

1. Call analytics_read with from and to. Each section has its figures, its answer and the same section in previous.
2. Use each answer as the lead sentence. Its proof figures come from the same report.
3. Call analytics_records with a result metric and the same filters to list the records behind that result.
4. Call analytics_configuration for the goals and their targets, and analytics_live for the last 5 minutes.

The Report on analytics job follows these steps. It changes nothing.

See website, shop and widget insights for setup, metric definitions and unavailable measurements.

Content reports include exact requests by case and tag, topic subscriptions, sent emails, unsubscribes, questions by guide step, and acknowledgements by version. These use the same date and access filters as the screen. Counted activity stays separate.

Analytics records, live view and configuration

Records behind a money result need View financial summaries. A goal archive keeps the goal's history. Saved analytics views belong to the person who saves them.

Prepare listing information

The delegate needs Manage listings, or current assignment and ordinary CRM access for reads. Tools use the platform workspace. A platform permission does not grant access to a customer workspace.

The generic widgets_requests_get tool applies the same access rule to listing requests. It still needs the forms:read scope. Owning an earlier lead does not grant access to a later listing request.

Read returns the same permitted listing facts, exact price and history as the screen. Request reads include the contact, snapshot, follow-up state and permitted private file links. Downloads still require the person's current access.

Preparation needs payload and an idempotency key. Supply listing_id and payload.version for an edit. Use the listing editor's fields: title, description, template, transaction, currency, decimal-string price or price_on_request, location fields, agent_id, show_closed, facts and ordered media. Each media entry has a file id, kind and an optional version_id; an omitted version uses the current version.

The server validates facts against the chosen template and derives minor units. Do not send a workspace, creator, stored minor units, publication date or status. The result has written: false and a review_url for the ordinary editor.

A person saves a listing. An AI client can change its availability with listings_availability. With the delegated person's approval, it can publish or withdraw a listing and move an enquiry, viewing or application to its next step, which emails the visitor. See Approve sensitive steps. Read the listing guide for the human workflow.

Availability and request files

Booking tools

These tools use platform booking permissions; customer workspace records are excluded.

Read access requires booking management permission or follow-up permission for that assigned booking. Preparation requires booking management permission.

bookings_prepare needs widget_id and selection. Selection contains schedule_id, visitor_timezone and party, with start for times or from and until for resource dates.

Use a UTC ISO timestamp for start, such as 2026-11-10T09:00:00Z. Resource dates use YYYY-MM-DD in the business timezone.

The response contains written: false, reserved: false, the exact price and a review_url. Open that URL to review current availability and terms.

The visitor supplies their own contact details and accepts the policy. Preparation does not hold capacity or create a booking.

booking-definitions_prepare needs the complete ordinary service-editor payload. For an edit, also supply definition_id and payload.version.

The response opens the ordinary editor with proposed values. A person checks and saves them; preparation does not publish a widget.

booking-definitions_save saves that ordinary payload immediately through the same definition action. For an edit, include definition_id and current payload.version.

Its idempotent receipt contains the definition ID and version. It does not publish a widget or reserve a place.

Use catalogue_item_id for an active shared service when linking an eligible platform definition to shop checkout. The ordinary source and booking permissions still apply.

Both preparation calls require an idempotency key: the HTTP Idempotency-Key header or MCP idempotency_key argument.

Booking settings, schedules and invoice drafts

These tools make the changes a person makes in booking settings and on a booking, as that person and through the same action as Pepper. Each write needs an idempotency key and appears in the record's activity as done by an AI connection for that person.

A staff schedule carries its person's name. A feed address is a secret: an AI client never reads one, never adds a feed and never changes a feed's address. It can change a feed's name, schedule, check interval and failure rule, check it again or remove it. bookings_invoice_draft makes a draft at the booking's accepted price; issuing stays with a person.

With the delegated person's approval, an agent can reschedule or cancel a booking, record that it was completed or a no-show, and send a failed booking email again. See Approve sensitive steps. Agents cannot reserve places, accept waitlist offers or connect calendar feeds. Private calendar addresses never appear in these responses.

Read Take and manage bookings for the complete human workflow and recovery limits.

Menus, estimators and service areas

Use widgets_get and widgets_prepare with the fields shown by the ordinary editor.

Read the current widget and source versions before preparing an edit. Supply both versions. The returned review link opens the editor for human review.

Menu item details have separate read and prepare tools:

Both tools require the delegated person's items.manage permission. Reads include shared details and author/time history, with an optional page argument.

Preparation accepts item_id and payload. The payload includes version, allergens, dietary, availability, translations, and an optional photo.

Allergen keys are gluten, crustaceans, eggs, fish, peanuts, soybeans, milk, nuts, celery, mustard, sesame, sulphites, lupin and molluscs. A photo uses file_id and alt; each language variant uses locale, name and description.

Supply an idempotency key as the HTTP header or MCP argument. Preparation returns written: false and a review link; it changes no menu detail.

Agents cannot save profiles or submit visitor requests. A person reviews the proposed values and saves them through the screen. Publishing the widget needs the person's approval of widgets_publish; see Approve sensitive steps. A widget that shows a form is published after its form (forms_publish).

Read menus and catering, estimators and service-area checks for limits and recovery.

Connection widgets

Link pages, locations, testimonials, downloads, feedback, surveys and polls use widgets_get and widgets_prepare with the same fields as their editors.

Read existing configuration before preparing an edit. Include the widget version and the source’s current version. The returned review link opens the ordinary editor. A person still saves and publishes.

Location reads and preparations require settings.manage. A location payload contains name, address, optional phone, active, weekly and closures. Each weekly row has day (Monday 1 to Sunday 7), open and close in HH:MM; closures are YYYY-MM-DD dates. An edit adds location_id and payload.version.

Invitation preparation needs widget_id, payload.customer_id and optional payload.expires_days (1–90). Feedback also needs payload.source_type (project or booking) and payload.source_id. The completed work and recipient must match. These preparation tools create no personal link and send no message. The separate widgets_request_send action emails a personal link after approval.

Both preparation tools require the HTTP Idempotency-Key header or MCP idempotency_key. They return prepared: true, written: false, normalized payload and review_url. The location link opens the location editor; the invitation link opens Requests and answers with the proposed customer.

Response reads require the owning widget’s permission. They return immutable questions, answers, consent and scoped file metadata. File bytes come through a single-use download link (widgets_response_file). Reports return version totals, sent-request counts, rating distributions, question counts and source/staff groups. They contain no public grant.

These tools use the delegated platform scope. Customer workspace records are not exposed through a platform connection. Guests and revoked or expired connections receive no data. With the delegated person's approval, an agent can publish or withdraw a widget, show or hide a testimonial and send a response request. See Approve sensitive steps. Agents cannot submit customer words or withdraw consent.

A response file opens once through a download link valid for five minutes, and Pepper checks the person's access again when it opens. A revoked request link stops working at once; answers already given stay.

Read the connection task guides for field limits, delivery states and privacy rules.

Content records and recipient proposals

These tools belong to the content widgets. They require Manage content and their named connection grants.

The report accepts a widget id, optional page and optional exact record ID. It returns scoped versions, recipient decisions, topic consents and delivery states. It excludes request tokens and private mail payloads.

The proposal needs widget_id, payload.customer_id and an idempotency key. HTTP uses Idempotency-Key; MCP uses idempotency_key. It validates an existing customer and returns a human review link. It creates no invitation and sends no email. Each call rechecks current access and the submitted contact. Revising a proposal creates no business record.

An AI client can revoke a request link. With the delegated person's approval, it can publish content with widgets_publish and send a consent, update or guide request with content_request_send. See Approve sensitive steps. Agents cannot give consent, subscribe an address or acknowledge a guide. See cases, updates and guides.

Customer decisions

They use the delegated person's Platform project permissions and current customer, project and deal access. Guests and customer workspace connections have no access.

List accepts optional project_id, customer_id and page. It returns 25 records per page. Read uses the case ID and accepts separate versions, history, questions, answers, stages and notices page numbers. Pages start at 1. Read returns permitted history, version hashes, mail outcomes and exact durations. It returns no file bytes, email codes or customer sessions.

Preparation requires payload and an idempotency key. For an edit, supply widget_id plus current widget and source versions. The payload uses the ordinary widget fields, including name, type, source, origins, language, theme, accent, show_title and enabled.

The count cannot exceed the number of files. Rule one requires count 1. Stage keys start with a lowercase letter and contain at most 40 lowercase letters, digits or underscores. Stage labels allow 160 characters. A project manager must create or change the stage list. Hour values are integers from 1 to 8,760. A prepared proposal is limited to 12,000 encoded bytes.

The result has written: false and a review_url. A person opens the ordinary editor, checks the proposal and saves it. With the delegated person's approval, an agent can publish the page with widgets_publish, ask or reopen a question, move a job stage, close a job, and send reminders and failed emails again; each emails the customer. See Approve sensitive steps. Agents cannot grant access, approve proofs, answer questions or accept quotes for the customer.

Read proofs and approvals and job progress for the human controls and recovery steps.

Offers and the counter

These tools read the offer claims, stamp cards and counter events of your offer widgets. They need Manage offers and stamp cards; the counter tools need Confirm and correct counter visits.

offers_counter_check reads what a code shows and changes nothing. A person confirms a stamp or redemption at the counter in Pepper. A code that Pepper does not know returns 404; an expired code returns 410.

Widget launcher tools

These tools use the same Laravel actions as Widgets > Widget launchers. Read launcher setup and limits.

The delegate needs Manage forms for Platform launchers and current management access to each selected widget. An explicit workspace_id selects one customer account. That delegate must also own the selected account. Omitting it selects Platform; it never means the current customer account. A customer login alone does not create a Platform agent connection.

Use widgets_launchers_save_prepare, widgets_launchers_publish_prepare or widgets_launchers_delete_prepare to request approval. Their matching execute tools end in _save, _publish and _delete. The tool reference lists each exact HTTP path. Get input and output schemas from GET /api/v1/tools or MCP tools/list.

Save needs name, website_id and an ordered items array. Each item has widget_id, an optional plain label and an optional existing placement_id. Get allowed values from widgets_launchers_options. Never choose the first returned widget without the person's instruction.

For website_id, use a returned website ID or an exact permitted origin, such as https://example.com. Each widget's website_ids lists its website choices. any_website: true means the published widget allows any valid website origin. If the website options are empty, enter an origin for your unrestricted widgets. Every selected widget must allow that origin.

An edit also needs launcher_id and its current version. Saving closes publication. Publish needs the launcher id, its current version and publish: true; use false to close it. Delete needs its current version.

Each preparation and execution needs its own idempotency key. The person reviews the exact website, order and services in Pepper. Changed widget versions, placements, permissions, membership or launcher configuration make an earlier approval stale. Repeating the same accepted execution returns its existing result. A changed request cannot reuse that approval.

These tools never answer a visitor question, give consent, complete a booking or share an identity across widgets. Those actions stay with the visitor.