> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finalsay-hitl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

# How it works

End-to-end flow: your automation creates an approval, teammates are notified (for example via **push** on mobile), someone responds in the **web dashboard** or **mobile app**, and your automation receives the outcome—either by **callback** or by **polling**.

The sequence diagram below shows the mobile path; **responding in the browser** uses the same API behind the scenes.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant Auto as Your_automation
  participant API as FinalSay_API
  participant Notify as Push_notifications
  participant Mobile as Mobile_app
  participant Human as Approver

  Auto->>API: POST /v1/approvals
  API-->>Auto: approval_id request_id expires_at
  API->>Notify: optional_push_to_subscribers
  Mobile->>API: load_pending_approvals
  Human->>Mobile: choose_option_or_custom_text
  Mobile->>API: submit_response
  API->>API: resolve_single_winner

  alt Callback_URL_provided
    API->>Auto: POST_callback_with_final_JSON
  else Polling
    Auto->>API: GET /v1/approvals/:requestId/result
    API-->>Auto: pending_or_final_JSON
  end
```

## Steps in plain language

1. **Create** — Your automation sends `POST /v1/approvals` with question, context, and options. **`timeout` is optional** on REST: omitted values are filled from the agent’s [dashboard defaults](./agent-settings#default-timeout); you can override part or all of timeout per request if needed. [MCP](../integrations/mcp) exposes **`request_human_approval`** and **`create_approval`** for the same create (no `timeout` in tool args—only those defaults apply). `request_id` is optional (the API can assign a UUID); include your own when you need a stable id for idempotent retries. See the [Agent API](../api-reference/agent) for the exact JSON.
2. **Notify** — **Subscribers** may get a push on **mobile**; if no subscribers are configured for the agent, the service may fall back to **all workspace members** (see [Agent settings](./agent-settings#subscribers)). Anyone with access can also open the **web dashboard** or **mobile app** and see pending work.
3. **Respond** — One person resolves the approval by choosing an option or entering custom text (in the browser or on a device).
4. **Deliver** — If you provided a **callback URL**, the service POSTs the final result there. Otherwise your automation **polls** `GET /v1/approvals/:requestId/result` until the result is no longer pending.
5. **Expire** — If time runs out, the request expires according to the timeout mode you set.

## Resolved result (polling)

When the result is ready, the polling endpoint returns JSON including fields such as:

* `request_id`, `agent_id`, `correlation_id` (if set)
* `status`
* `selected_option_index`, `selected_option_label` when an option was chosen
* `custom_instruction` when used
* `resolved_by`, `resolved_at`

Full field list and error codes: [Agent API](../api-reference/agent).

## Related

* [Web dashboard](./web-dashboard)
* [Credentials](./credentials)
* [n8n](../integrations/n8n) · [Zapier](../integrations/zapier) · [MCP](../integrations/mcp)
* [Glossary](../concepts/glossary)