Choosing the right item type
An intake is only as good as its items. Pick text where you meant select, or file where you meant image, and the client either sends something that doesn't validate as expected, or something valid that still isn't useful — a screenshot instead of a vector logo, a paragraph where a yes/no would have done. BriefGate has twelve item types. This is a guide to picking the right one, not a list of what each does — for the field-by-field reference, see Item types.
Start from what you're actually asking for
The type isn't a formatting choice, it's a contract: it decides what the portal shows the client, what gets validated before they can submit, and what shape get_intake_results hands back to you. Three questions narrow it down fast:
- Is this a file, or a value? A logo is a file. A brand color is not — even though a client might think of it as "the blue from our logo," what you actually want back is a hex code, so it's
color_list, notimage. - Is there a fixed set of acceptable answers? If yes, that's
selectormultiselect, nottextorlongtext— see below for why that matters more than it looks like it should. - Does the client choose it, or do you? Most items are
assignee: "client"by default. A to-do that's actually yours — "call the client", "register the domain" — isassignee: "owner"instead, and never reaches the portal at all.
Text vs. longtext vs. structured
text is for short, single-line, structured strings: a GA4 measurement ID, a tracking code, an account name. It defaults to a 2000-character cap and accepts a top-level pattern (an ECMAScript regex) to enforce a specific shape, like ^G-[A-Z0-9]+ for a GA4 ID.
longtext is for prose — bios, mission statements, hero copy, anything the client needs room to actually write. Its default cap is much higher (20,000 characters), and in practice you'll usually tighten it with max_chars so a "short intro" item doesn't come back as three paragraphs.
structured is for a value with more than one field that belongs together — opening hours with mon_fri/sat/sun, a services list, a contact block with phone/email/address. You define a JSON Schema and the portal renders a form from it: a flat object, a repeatable list of such objects (say, up to six services), or a list of single values. Keep the schema to those shapes, because deeper nesting and constructs like oneOf have no form for the client to fill in. What comes back through get_intake_results is validated against the schema on the server. The mistake to watch for: three separate text items for phone, email, and address is a worse fit than one structured item with those three properties — the free-standing items don't say they belong together, and there's nothing stopping the client from filling in two of three.
select vs. multiselect vs. free text
This is the single most common item-type mistake: asking a free-text question where the real intent is a limited set of choices. "What platform do you want?" as a text item gets you "wordpress", "Wordpress", "WP", and "not sure, whatever's easiest" from four different clients — four strings your downstream process now has to normalize by hand. The same question as a select with defined options (value/label pairs) returns exactly one of the values you defined, every time, with no normalization needed.
select is for exactly one answer from a defined list. multiselect is for several answers from a defined list — "which services do you need," where more than one can apply — and the client ticks a checkbox for each one that does. Items are required by default, and a required multiselect needs at least one tick: set required: false when "none of these" is a real answer, and min_count/max_count when you need, say, at least two and at most four. The result for select is always the value string, never the label the client saw; for multiselect it's always an array of value strings, even for one pick. Whenever more than one answer can be true, use multiselect rather than select — coercing a multi-answer question into select just pushes the client toward one option and leaving the rest unsaid.
Reserve boolean for a true yes/no question — "do you have an existing website?" — rather than a two-option select; it renders as a Yes/No button pair instead of a dropdown with two rows, and the result is a plain true/false.
file vs. file_list vs. image
file is one file: a signed PDF contract, a font file, a spreadsheet — anything where you need exactly one document and don't care about its pixel dimensions.
file_list is a group of files under one item — a photo gallery, an asset pack — with min_count/max_count to enforce how many. It avoids a single catch-all "send me everything" file item: a client asked for one file sends one file, even if what you actually wanted was eight photos and a logo. Ask for what you need as separate, specifically-labeled items — or a file_list for a genuine group of similar files — instead of one item that quietly depends on the client reading your intent into the label.
image is for when the file is an image and you care about more than just "it's a file" — minimum or maximum width and height, allowed formats, a size cap. Use image instead of file whenever you'd otherwise have to eyeball the upload afterward; BriefGate rejects an upload that breaks those constraints before it is accepted, so a 200px logo never reaches you in the first place. Unlike file, image's constraints.formats has no default — any image format is accepted unless you set it, so list your allowed formats explicitly if you need to rule out, say, HEIC.
url and secret
url validates that the value is a proper http/https URL (a client who types firma.cz gets https://firma.cz). It doesn't restrict the domain, so when you specifically want, say, a Google Drive link and not any URL at all, say so in the item's help.
secret is for credentials — CMS logins, API keys, anything that shouldn't sit around in plaintext. The value is sealed on the server with a libsodium sealed box before storage, never logged or included in webhook payloads, and can be revealed through get_intake_results only once (with a short grace window for a caller whose first read never arrived). That's encryption at the server, not end-to-end or zero-knowledge — worth being precise about when describing the security model to a client. Use secret for anything a client would call a password, text for anything else, even if it looks credential-adjacent (an account ID isn't a secret; the password to it is).
Common mistakes, summarized
- A file item for a decision. "Send me your logo file with your color preferences noted" is really two items: an
imageand acolor_list. Splitting them means each validates on its own, and the intake isn't complete until both are in. - Free text where a choice belongs. Any time you'd have to normalize the client's answer afterward — matching "wordpress"/"WP"/"Wordpress" back to one value — that's a sign the item should have been
selectormultiselect. - One giant "send me everything" item. A single
fileorfile_listitem covering unrelated materials (logo and photos and the signed contract) lets the client satisfy it with just one of those things. Give each category of material its own item, even if the intake ends up with more rows. assignee: "owner"on a client question, or vice versa. An owner item never reaches the portal and never holds the intake open, so a genuine client question set toassignee: "owner"simply never gets asked. Your own to-do items don't belong as client items just because it's convenient to track them on the same intake.
Try the types on one intake
Create a free account, no card required. Free covers one active intake with up to 10 items, enough to put a select, a multiselect, a boolean and an image on one intake, send it to an address of your own and open the portal your client would get. secret items start on the Solo plan.
Related
- Item types — the full reference: constraints, examples, and exactly what
get_intake_resultsreturns for each type - Templates — built-in item sets that already make these choices for a few common project types
- Dashboard quickstart — building an intake's item list from the browser