Ask a person
Asks 1 to 25 named people for a decision or input through a human task with your own form. Requires an External App or a platform key holding human_tasks:use.
v2 compatibility notes
Creates a human task of kindexternal_app_request that asks 1 to 25 named people for a decision or
input. You declare the form: its fields (form.schema) and its actions (form.actions). People answer
in the Forge Console, Slack or email. Software never answers a human task, yours included.
Who may ask
Call it as an External App (its OAuth token or its companion key) or with a platform key. A Personal key acts as a person, so it is refused with403 and no error.requiredPermission: no grant remedies it.
The credential must hold human_tasks:use, a permission an operator gives it through a role. No
preset and no default role includes it. An External App’s token must also name human_tasks:use in
its scope, so an app asks people only when an operator granted it and its token asks for it. The
grant may be at the deployment or at a sub-unit: Forge checks it where the people asked are homed,
and checks it again at the task’s home whenever you read or withdraw the ask.
You ask as yourself: the body never names who asks. Forge stamps the task with your app or key, and
every surface shows a server-built line above the task, such as
Requested by the External App “Vendor desk”. Your app’s name appears only inside the quotes. Every
task also shows the fixed line “Forge never asks for passwords or codes in a request.” Email copy for
your task shows any link in your text inert (hxxps://example[.]com), and Slack shows your text
verbatim, with no links or mentions.
Who can be asked
Each target is one person,{ "type": "person", "personId": "…" }. Groups are not supported. Your
human_tasks:use grant must cover each person’s home organization unit. A grant at a sub-unit reaches
only the people homed under it. If any target is unknown, inactive, has no home or is outside your
reach, the whole request is refused with one answer, no_candidates, whatever the cause.
The task’s home is the deepest unit that covers every person asked. A person may take one of your
declared actions only while holding eligibilityPermission at that home. It must be a catalog
permission that is not elevated: no approve verb, no platform:manage, no administer key. Anyone
asked may decline with a reason, whatever they hold.
The form
form.schema is a flat object of fields, and form.actions lists 1 to 6 actions
(id, label, optional doneLabel, style and requires). Forge appends a reason field and a
Not me (decline) action. The server makes every action you declare a permit with no extra
assurance, so the eligibility check runs on each of them.
A form is refused (form_invalid, with the first problem in the message) for: a file, JSON or list
field; an unknown key; an unsafe pattern; an action id decline or withdraw; a field named
reason; a requires that names no field; a choice list with no options; more than 6 actions, 20
fields or 50 options; a label
over 75 characters; a description or default over 500 characters; an option value over 100
characters; or an ask whose title, summary, detail and form together are over 12,288 bytes (UTF-8).
A form or text that asks for a password, code or key (a default and an option value included) is
refused with form_secret_like. Look-alike letters and spaced-out words are folded before that check.
Answers and limits
error.reason. A due date runs from 15 minutes to 14 days
(dueInMs; 72 hours by default). At the due date an unanswered task is canceled with
cancelReason: "due_date", and nothing escalates. When everyone asked declines, it is canceled
with declined.
The window caps count every ask you created, open or closed, so withdrawing does not free them. The
deployment ceiling of 200 open asks keeps a person merge, which reads every open task in one
step, within its read limit.
If your app is deactivated or deleted, your key is revoked or expires, or your grant no longer covers
the task’s home, your open asks are closed (superseded) before any follow-up. No webhook is sent for
that close, because the requester can no longer receive one. Read the ask to see it.
Learning the outcome
An External App that subscribes tohuman_task.completed and human_task.canceled hears about its
own asks. The event carries ids only. Read the answer with
Read one of your asks. A platform key
has no webhook path of its own: it polls that read. See
Webhooks.
Example
201 with { "data": { "humanTaskId": "…", "clientReference": "vendor-4711", "created": true, "state": "created", "dueAt": …, "candidateCount": 1, "handoff": { … } }, "meta": { "requestId": "…" } }. The handoff names the task’s Console link
(/my-work?item=external_app_request%3A<id>).Authorizations
Headers
Body
Ask 1 to 25 named people for a decision or input. form declares the fields and the actions that answer it; every declared action needs eligibilityPermission at the task's home, and decline (with a reason) is always added. A form that uses files, JSON or list inputs, asks for a password, code or key, or exceeds 20 fields, 50 options, 6 actions, 75-character labels, 500-character descriptions or defaults, 100-character option values, or 12,288 bytes for the title, summary, detail and form together is refused with 400.
Response
A repeat of a client reference you used before: that ask

