Concepts

Elicitations

Use an elicitation when your agent needs information a person has to provide — a missing date, a category decision, a confirmation it can’t derive. You define a typed form per request; the human fills it in; the agent reads the answers back.

The flow

Like an approval, an elicitation is a request you create on a task and poll for. The difference is the payload: instead of a yes/no, you declare a list of typed fields, and the result carries the human’s answers keyed by field id.

1import time
2import uuid
3
4from pumpup import PumpUp, Field_DateField, Field_Select
5
6client = PumpUp()
7
8request = client.elicitations.create(
9    idempotency_key=str(uuid.uuid4()),
10    project_name="claims",
11    task_id=task_id,
12    summary="Need a couple of details on the incident",
13    fields=[
14        Field_DateField(id="incident_date", label="Incident date", required=True),
15        Field_Select(
16            id="coverage_type",
17            label="Coverage",
18            options=["collision", "comprehensive"],
19            required=True,
20        ),
21    ],
22)
23
24while True:
25    result = client.elicitations.get_result(id=request.event_id)
26    if result is not None:
27        break
28    time.sleep(2)
29
30answers = result.fields  # {"incident_date": "2026-05-14", "coverage_type": "comprehensive"}

Field types

Each field is one of a fixed set of typed arms. Common to all: id (the key the answer comes back under), label (the human prompt), an optional description, and required. Per-arm options:

FieldPython class / wire typeOptions
Short textField_Text / Textlength bounds; format hint EMAIL / PHONE / URL
Long textField_TextArea / TextArealength bounds
NumberField_Number / Numbermin / max; integer_only
SliderField_Slider / Sliderrequired bounds; optional step
Single choiceField_Select / Selectnon-empty options
Multiple choiceField_Multiselect / Multiselectnon-empty options
Date / time / datetimeField_DateField / Field_Time / Field_DateTimeinclusive bounds (zone-naive)
ToggleField_Switch / Switch—

The date arm is DateField, not Date, so the generated SDK types don’t clash with the built-in Date.

Recommending answers

If the agent has a lean on a field, send a per-field recommendation — an array of bids. The value doubles as the reviewer’s pre-fill.

1from pumpup import FieldBid
2
3request = client.elicitations.create(
4    idempotency_key=str(uuid.uuid4()),
5    project_name="claims",
6    task_id=task_id,
7    summary="Confirm the coverage type",
8    fields=[
9        Field_Select(id="coverage_type", label="Coverage",
10                     options=["collision", "comprehensive"], required=True),
11    ],
12    recommendation=[
13        FieldBid(field_id="coverage_type", value="comprehensive",
14                 confidence=0.92, rationale="Hail damage pattern."),
15    ],
16)

Each bid’s field_id must match a declared field id. Answers are validated against the field on submit — wire type, bounds, option membership, and text format.

Approvals

Ask for sign-off on an action instead of input.

API reference

The full field schema and result shape.