Get Forms
/v1/kb/formsorg.permission.kb.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Gets all forms. Use include=snippets to include related snippets.
Knowledge base forms
A form is a contact form on your help center, such as "Contact support" or "Report a problem". When a customer submits it, Kustomer opens a conversation with their answers, or hands the submission to a form hook for a workflow to process.
Forms let customers reach your team from the help center without email or chat. Admins build them in the knowledge base settings, and the help center displays them to customers. A form is a draft until you set published: true. Only published forms appear in the help center, and only published forms accept submissions. A form can belong to one knowledge base through knowledgeBase. Its hash and slug identify it in help center URLs, and Kustomer generates both if you don't send them.
What a submission creates
By default, a submission creates a conversation. klass sets the type of record it creates, and conversation is the only value. channel sets the conversation's channel, and email is the only value. Other settings change how a submission is handled:
| Field | Effect |
|---|---|
recaptcha |
Shows a reCAPTCHA check before the form can be sent. On by default. |
deflection |
Suggests related articles while the customer fills in the form, so they can find an answer without submitting. |
formHookEnabled |
Sends submissions to a form hook instead of creating the conversation directly, so a workflow decides what to do with them. |
Layout and fields
The editor saves a form's fields in layoutV2, which holds the rows and their order, and componentsV2, which is a map of field definitions keyed by component ID. A field that collects data names the attribute it fills, such as a standard or custom conversation or customer attribute (attributeProperty, attributeType, isCustomAttribute). layout and components are the older format of the same data. An advanced form is a live-code form, written as code in body instead of in the editor. Live-code forms can't use the built-in submission that creates a conversation.
Labels and help text can contain snippets, Kustomer's translatable text, so one form works in every help center language. List the snippet keys the form uses in snippets. Each key must already exist, or Kustomer rejects the form. Add include=snippets to a read to get their values.
Which endpoint to use
| To | Call |
|---|---|
| List forms, or read one | GET /v1/kb/forms or GET /v1/kb/forms/{id} |
| Create a form | POST /v1/kb/forms |
| Edit, publish or unpublish a form | PUT /v1/kb/forms/{id} |
| Delete a form | DELETE /v1/kb/forms/{id} |
| Render a form in a help center or your own site, without an API key | GET /p/v3/kb/forms/{id} |
The public endpoint returns a published form, with snippet text localized to lang. Add preview=true to load the unpublished version instead, for example to preview changes. Like the other public knowledge base endpoints, it needs no API key and works out the org from the host, so call your org host. Reads need a knowledge base read role, and writes need org.admin.kb.write or the matching permission.
Query parameters
Page number of results to return.
1Number of results to return per page.
100Comma-separated related resources to include.
"snippets"Responses
OK