Forms & surveys
A form is either a sign-up form, which brings in contacts with marketing consent, or a survey, which asks questions and saves the answers on the contact. Both are built under Forms & surveys in the app, or through the API (/api/v1/signup-forms).
Three ways to share one
| Where | How | Who answers |
|---|---|---|
| A page of its own | pageUrl: https://crm.codefab.dev/public/f/{id} | Anyone with the link, with their email address |
| Your website | <script src="https://crm.codefab.dev/public/signup/{id}/embed.js" async></script> where the form should appear | Anyone, with their email address |
| An email | Put emailLinkTag ({{forms.<slug>}}) in a template, e.g. as a button's link | The recipient, without typing anything: the link is signed for them |
A personal link only works for its own form and its own contact. It does not expire, but it stops working when the form is switched off or the contact is deleted. A changed or broken link is not trusted: the page asks for the email address instead.
Questions
| Type | Answer saved as |
|---|---|
short_text, long_text | text (up to 500 / 5,000 characters) |
single_choice | one of options |
multi_choice | a list of options |
rating | a number 1–5 |
nps | a number 0–10 |
number | a number |
date | YYYY-MM-DD |
yes_no | true / false |
Each question gets a key from its label when it is first saved, and keeps it: renaming a question is safe. A question's type can't change once it has answers. Add a new question instead.
A multi_choice question can set min and max: how many options a person must and may tick. The form says so under the question ("Choose 1–2.") and stops more boxes being ticked at the maximum. A contact field that holds several choices takes the same min and max in fields.
Text, order and banner
A form can show information between its inputs, such as a schedule, terms or a note about food.
- Text blocks (
texts, up to 20, each up to 5,000 characters) use simple formatting:# Heading,## Smaller heading,**bold**,- bullet(indent it for a second level),[label](https://…)or a bare https link, and---for a divider. A blank line starts a new paragraph. Anything else is shown as plain text. - Order (
layout) lists everything on the form from top to bottom:t:<text key>,f:email,f:<field key>andq:<question key>. A question that has no key yet can be named by its place inquestions, counting from 0:q:#2. Anything left out follows in the default order: text blocks, email, fields, questions. - Banner (
banner:url,alt) is a wide image across the top, cropped to about 3:1. It must come from your image library (Templates → Images); on the form's own page it is also the picture shown when the link is shared.
{"texts": [{"key": "schedule", "text": "## Schedule\n- 16:00 Welcome drinks\n- 17:30 Dinner"}],"layout": ["t:schedule", "q:#0", "f:first_name", "f:email"],"banner": {"url": "https://crm.codefab.dev/public/email-assets/…/….jpg", "alt": "Our office"}}
Leave out all three and a save keeps what the form already has.
Texts after signing up and in the confirmation email
What an email sign-up form shows once someone has signed up is one of your texts to contacts: Settings → Brand → Pages and emails to contacts, page "After signing up", in each language. A form's own successMessage wins over it.
With double opt-in, the confirmation email uses the same place's wording. A form can have its own text and button for it (confirmText, confirmButton), for example for one event, without changing the email for every other form. Empty uses your organisation's; left out keeps the form's own.
Deleting or switching off
Deleting a form removes its page, link and embed. The answers stay on each contact's timeline, but the form's results and CSV export go away. To stop new answers and keep the results, switch the form off instead (active: false).
Answers are events
A survey's answers are recorded as one event on the contact, config.eventKey (for example form.after_purchase), with one payload field per question. That makes them usable everywhere events are:
- Segments: "answered How likely… with 9 or more" (below).
- Automations: start a flow when the event arrives (a thank-you, or a call for a low score).
- Webhooks: subscribe to the event type.
{"type": "event", "eventType": "form.after_purchase","where": [{"field": "how_likely_are_you_to_recommend_us", "operator": "gte", "value": "9"}]}
The event type is created and kept in step with the questions by the form; it can't be deleted while the form exists.
Look
Forms wear the organisation's brand (Settings → Brand, the same one emails use). On a form's own page that is the whole brand: font, colours and button. Embedded on your website, it is only the button colours and corners, so the text keeps your site's own colours. A form's styling overrides any part of it, and your site's CSS can restyle every part: see Style your form.
Against spam, every form has a hidden trap field and a limit per IP address. For more, switch on a CAPTCHA per form: see Protect your form with CAPTCHA.
The brand also holds two texts for your forms, so you write them once: consentText, the sentence next to the email-consent checkbox, and successText, what an email sign-up form says once someone has signed up, for example "check your inbox and confirm". A form with its own text keeps it; the ready-made forms from the Market take yours once it is set. SMS forms keep their own, and surveys keep "thanks for your answers". Set them under Settings → Brand, or with PUT /api/v1/email-brand.
Ready-made surveys
The Market has an NPS survey (with an invite email, Promoter and Detractor segments and a follow-up automation), a satisfaction survey, an event-feedback survey and a product-interest poll. Each installs in one click and can be edited afterwards.
Copying a form
Duplicate (or POST /api/v1/signup-forms/{id}:duplicate) makes a switched-off copy with the same questions and look. It gets its own link and its own answers event, and starts with no answers. The original's results stay with the original.
Settings that matter
oneAnswerPerPerson: a second answer is refused. Strict with personal links; on the open page a person is recognised by email address.askConsent(surveys): offers an optional marketing-consent box. Ticked → consent is recorded; not ticked → consent is left as it was. Sign-up forms always require it.language:svoren, for the words around your own texts ("Required", errors, "Answering as").closedMessage: shown while the form is switched off.doubleOptIn: people confirm their address through an email before they count as consenting. That email goes out through your email provider (Settings → Email): without one nobody gets it, and the sign-ups stay unconfirmed. The forms page and Settings → Email warn when that is the case and list the people whose confirmation email didn't go out, with Send again;GET /api/v1/signup-forms/confirmation-emailsgives the same.
Results
GET /api/v1/signup-forms/{id}/summary: per question, the answered count, counts per option or score, the average, NPS (promoters 9–10 minus detractors 0–6, in percent) and the latest text answers.GET /api/v1/signup-forms/{id}/responses?page=0&size=50: every answer, newest first, with the contact and whether it came through a personal link.GET /api/v1/signup-forms/{id}/responses.csv: the same as a spreadsheet (UTF-8, one column per question).
Errors you may see
| Code | Status | Meaning |
|---|---|---|
invalid_answer | 400 | An answer doesn't fit its question; question names it |
link_invalid | 400 | The personal link was changed or its contact is gone |
already_answered | 409 | One answer per person, and this person has answered |
question_has_answers | 409 | Tried to change the type of a question that has answers |
event_used_by_form | 409 | Tried to delete the event (or a field) a form saves its answers in |