---
title: "Poll signup handoff status"
method: GET
path: "/api/v1/signup/sessions/{session_id}"
tags: ["Signup"]
---

# Poll signup handoff status

`GET /api/v1/signup/sessions/{session_id}`

## Request

- Base URL: `https://www.poster.ly`
- URL: `https://www.poster.ly/api/v1/signup/sessions/{session_id}`
- Auth: none required

Pollable status feed for AI agents that started a posterly signup (a 7-day card-backed free trial).
While checkout is open, the response includes payment: trial terms, merchant and what an agent may do. payment is null once the card is saved or checkout has expired. A completed trial Checkout reports status password_required, payment_confirmed or later; the statuses are unchanged and their messages say the trial started and the card is saved.
Use status_message and next_action to keep the user informed in the AI chat while Stripe checkout, password setup, and agent authorization happen in the browser.
If the session returns agent_access_required, the user must copy/install/authorize posterly access in the trusted AI before the agent can create connect sessions.
When the agent actually has posterly access, ask which social account to connect, call create_connect_session, send the connect_url, and poll the connect session.

## Path parameters

- `session_id` string, required

## Response `200`

Signup session status fetched successfully

- PublicApiSignupSessionResponse
  - `signup_session` PublicApiSignupSession, required
    - `id` string, required
    - `status` 'checkout_pending' | 'checkout_expired' | 'payment_confirmed' | 'password_required' | 'authorize_agent' | 'agent_access_required' | 'api_access_active', required
    - `status_message` string, required
    - `checkout_redirect_url` string, uri, nullable
    - `poll_url` string, uri, nullable
    - `complete_url` string, uri, nullable
    - `next_action` object, nullable
      - `actor` 'user' | 'agent' | 'posterly'
      - `type` string
      - `label` string
      - `description` string
    - `agent_next_steps` string[]
    - `agent_pay` PublicApiSignupAgentPay, nullable: Present when ENABLE_AGENT_CARD_PAY is on. Agents can confirm this prepaid PaymentIntent with a Link virtual card. Never send card numbers to posterly.
      - `enabled` boolean
      - `method` 'payment_intent'
      - `credential_type` 'card'
      - `amount` integer: Amount in the smallest currency unit, for example cents.
      - `currency` string
      - `amount_display` string
      - `payment_intent_id` string
      - `client_secret` string, nullable
      - `publishable_key` string, nullable
      - `confirm_url` string, uri
      - `poll_url` string, uri
      - `checkout_redirect_url` string, uri
      - `pay_instructions` string
      - `status` string
      - `requires_tos_acceptance` boolean: True until the user has explicitly accepted the posterly terms. While true, client_secret and publishable_key are null; POST { "tos_accepted": true } to confirm_url to receive them.
      - `period` object
        - `kind` 'prepaid_first_period'
        - `interval` string
    - `payment` PublicApiSignupPayment, nullable: Always present while checkout is open, regardless of agent card pay. Describes the Stripe-hosted Checkout session itself, including the free trial terms, so an agent with a reusable approved card can complete it, without a posterly-issued PaymentIntent. One-time virtual cards must not be used for a trial. null once payment is confirmed or checkout has expired.
      - `amount` integer, nullable: Amount due at checkout in the smallest currency unit, for example cents. null for a free-trial session (nothing is due today) and when Checkout has not populated amount_total yet.
      - `currency` string
      - `amount_display` string, nullable
      - `billing` 'monthly_subscription' | 'yearly_subscription' | 'weekly_subscription'
      - `description` string
      - `trial_period_days` integer, nullable: Free trial length in days, or null when the session charges at checkout.
      - `charged_today` boolean: False for a free-trial session: a card is collected and nothing is charged until day 8.
      - `merchant_name` string
      - `merchant_url` string, uri
      - `checkout_redirect_url` string, uri
      - `pay_with` 'stripe_hosted_checkout'
      - `agent_wallet` object
        - `supported` boolean
        - `how` string: Plain-language instructions for paying checkout_redirect_url with an approved agent payment credential.
        - `spend_request` object
          - `merchant_name` string
          - `merchant_url` string, uri
          - `amount` integer, nullable
          - `currency` string
          - `context` string: Short sentence for an approver. Never contains the user's email.

## Other responses

- `400`: Validation error
- `404`: Resource not found

---

[API](https://skmtc.dev/poster/apis/posterly-api.md) · [All operations](https://skmtc.dev/poster/apis/posterly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/poster/apis/posterly-api/revisions/60be02a61f95?raw)