What to Do When a Client Uploads the Wrong File
Call request_revision on that one item with a note describing what's wrong — from the dashboard or from your agent over MCP/REST. BriefGate flags just that item in the portal, emails the client, and the rest of the intake keeps moving; you don't re-send the whole thing or chase the correction yourself over email.
Why this needs its own step
A client can submit a file that passes every check BriefGate runs and still be the wrong file. A file item constrained to formats: ["pdf"] happily accepts a PDF that's the unsigned draft instead of the signed contract — the format is right, the content isn't, and no amount of format or size validation catches that, because BriefGate validates what it can verify mechanically (extension, size, pixel dimensions) and has no way to read the meaning of a document. The reference docs for item types are explicit about this boundary: "BriefGate does not infer constraints from file content or other heuristics." Catching the content mismatch is a human judgment call, made by whoever reviews what came in — and once you've made it, you need a way to send the client back to fix just that one item without derailing the rest of the intake or starting a side conversation by email.
Calling request_revision
From an agent, over MCP:
{
"intake_id": "in_8f3kQmR2",
"item_key": "signed_contract",
"note": "This is the draft without your signature — I need the signed PDF you received back from the printer, not the version you sent for review."
}{
"intake_id": "in_8f3kQmR2",
"item_key": "signed_contract",
"status": "needs_revision",
"client_notified": true
}The REST equivalent is POST /v1/intakes/:id/revision with the same item_key and note in the body; from the dashboard it's a button on the item itself, with the note typed into a text box instead of JSON. All three paths land on the same state change, and the call only succeeds when the item is currently submitted or approved — asking for a revision on an item nobody has touched yet returns a 409 conflict, since there's nothing wrong to flag.
What the client sees, and when
The client gets an email explaining a specific item needs attention, and it goes out the moment you call request_revision — it isn't queued for the client's next scheduled reminder slot the way an automatic chase is, and it isn't held back by quiet hours either, since this is a deliberate message about something specific rather than a generic nudge that can wait until morning. Clicking through takes them to the same portal link as always, where the flagged item now shows a banner with your exact note on it:
"This is the draft without your signature — I need the signed PDF you received back from the printer, not the version you sent for review."
Only that item is affected. Everything else they already submitted stays exactly as it was — approved items stay approved, other pending items stay pending — and the item's status moves back to needs_revision so the client can re-upload it in the same spot. The moment they do, it returns to submitted, its 72-hour auto-approval clock (or whatever you set auto_approve_hours to) starts over, and item.submitted fires again on your webhook the same as any first submission.
One distinction worth knowing if you're also using reminder schedules: a revision notice is not counted the way a scheduled reminder or a manual send_chase is against the intake's max_reminders cap. Reminders that arrive at a sensible hour covers that cap in full — the short version here is that asking for a fix on a specific item doesn't eat into the budget of general nudges the cadence has left before the intake stalls.
The Free plan doesn't have this
Revision requests need the revisions feature, which is not available on the Free plan — both the dashboard button and the MCP/REST call return plan_required there. On Free, the only path is to message the client yourself outside BriefGate and wait for them to resubmit through the portal, or to upgrade. There's no substitute built into send_chase: it sends the same generic nudge about everything still outstanding, with no note field and no way to flag one specific item.
Heading it off before it happens
A revision request fixes a wrong file after the fact; the item definition is what keeps most wrong files from arriving in the first place. Three things do the actual work:
formats, so an upload that's the wrong file type — a.docxwhere you need a signed.pdf, a.jpgwhere you need a vector.svglogo — is rejected before the client can submit it, in the browser first and then, authoritatively, on the server.min_width/min_heighton animageitem, so a logo exported at 200px for a social media post never reaches you labeled as the print-ready version.help, the one field that does the most unglamorous work of all. "Upload the signed PDF you received by email" next to the upload button heads off a surprising number of wrong files that would technically have passed every constraint — a client who sees an unlabeled upload box and a client who sees that sentence make different choices about what to attach.
{
"key": "signed_contract",
"label": "Signed project contract",
"help": "Upload the signed PDF you received back from the printer — not the draft you sent for review.",
"type": "file",
"required": true,
"constraints": {
"formats": ["pdf"],
"max_bytes": 10485760
}
}None of that replaces request_revision — a client can still misread the clearest help text, or upload the correct format with the wrong content — but it narrows the set of cases that ever need one. The two are complementary: constraints and help text handle "obviously wrong," and request_revision handles "looks right, isn't."
Related
- Item types — the full
constraintsreference forfile,file_list, andimage - Client portal — what the client sees end to end, including the revision banner
- Reminders that arrive at a sensible hour — how the
max_reminderscap works, and why a revision notice doesn't count against it - MCP tools —
request_revisionandget_intake_resultsin full - REST API —
POST /v1/intakes/:id/revision