Skip to main content
POST
Ask named people for a decision or input
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Creates a human task of kind external_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 with 403 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

Every other refusal names its code in 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 to human_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

The answer is 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

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json

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.

clientReference
string
required

Your own id for this ask: 1 to 128 of A-Z a-z 0-9 . _ -. A repeat of a reference you used before returns that ask (created: false), even a closed one; a reference is never reused.

Pattern: ^[A-Za-z0-9._-]{1,128}$
title
string
required
Required string length: 1 - 200
summary
string
required
Maximum string length: 2000
form
object
required
targets
object[]
required

The people to ask, 1 to 25, each inside your reach.

Required array length: 1 - 25 elements
eligibilityPermission
string
required

The catalog permission a person must hold, at the task's home, to take a declared action. It must not be an elevated permission (no approve verb, no administer key).

Minimum string length: 1
detail
string
Maximum string length: 10000
dueInMs
integer

How long the ask stays open, 15 minutes to 14 days; defaults to 72 hours.

Response

A repeat of a client reference you used before: that ask

data
object
required

The ask: its task, your reference, its state and due time, how many people it asks, and handoff, where they answer it in the Forge Console. created is false for a repeat of a reference you used before.

meta
object
required