Skip to content
AgentsForms Docs

Sessions

A session represents one human interaction with a form. The agent creates a session, sends the URL to the human, and the session tracks progress until submission or expiry.

Lifecycle

Section titled “Lifecycle”
created → open → submitted | expired
  1. Created: The agent calls POST /v1/forms/:id/sessions. The session is in created state.
  2. Open: The human loads the URL. The session transitions to open.
  3. Submitted: The human submits the form. The session moves to submitted.
  4. Expired: If the session reaches its expiry time without a submission, it moves to expired.

Create a session

Section titled “Create a session”
Terminal window
agentsforms sessions create support-intake \
  --expires-in 3600 \
  --prefill email=user@example.com

Or via API:

Terminal window
curl -X POST https://api.agentsforms.com/v1/forms/form_abc123/sessions \
  -H "Authorization: Bearer $AGENT...EY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in": 3600,
    "prefill": { "email": "user@example.com" },
    "metadata": { "thread_id": "thread_42" }
  }'

Session URL

Section titled “Session URL”

Each session gets a unique hosted URL:

https://agentsforms.com/f/sess_xyz789

Send this URL to the human via your agent’s existing message channel.

Prefill

Section titled “Prefill”

Populate fields with known values before the human sees the form:

{
  "prefill": {
    "email": "user@example.com",
    "session_id": "sess_internal_ref"
  }
}

Prefilled fields are still visible and editable by the human. Use hidden fields for values the human should not see.

Expiry

Section titled “Expiry”

Sessions expire automatically after the configured expires_in duration (default: 3600 seconds = 1 hour). When a session expires:

  • The URL stops accepting submissions.
  • A session.expired webhook event fires (if configured).
  • The session record is preserved for audit.

Partial submissions

Section titled “Partial submissions”

If the form has "allowPartial": true, the human can submit before filling every field. The agent receives a submission.created webhook with partial: true and can respond (e.g., ask for the missing fields or proceed with incomplete data).

Resume / extend

Section titled “Resume / extend”

Extend a session’s expiry:

Terminal window
agentsforms sessions extend sess_xyz789 --by 1800

Or via API:

Terminal window
curl -X PATCH https://api.agentsforms.com/v1/sessions/sess_xyz789 \
  -H "Authorization: Bearer $AGENT...EY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 1800}'