API reference: Agency

Roll reusable bundles out to client workspaces, schedule client reports and let a client approve a rollout, all from automation. Bearer-auth and team-scoped. Agency endpoints need a Team or Scale plan and a token from the agency workspace: agency:read to read, agency:write to change anything. Writing is for owners and admins. A client workspace is reachable only for people who hold an explicit grant for it; another agency's ids answer 404, a client without a grant answers 403.

The client approval endpoints are the other side of a rollout. Use a token from the client workspace with approvals:read / approvals:write; only a client admin can decide.

Base URL: https://formspring.io/api/v1

Bundles and rollouts

{version} is the version number. POST /agency/bundles takes a name, a selection (a type such as form, survey, funnel, booking_page, poll, bio_page, link, automation, knowledge_collection or knowledge_article mapped to a list of ids, plus theme: true) and optional replacements that turn literal text into a variable. It creates a draft version; a version must be reviewed and published before it can be deployed.

Deploying creates everything in the client workspace as drafts, all or nothing, and answers 202 while the rollout is prepared. Options:

• requires_client_approval holds the rollout until a client admin approves it.
• automations is inactive (default) or activate_ready; automation_keys switches on chosen automations at go-live.
• rebinds points domain and calendar slots at a destination that belongs to the agency or to the client. A destination owned by anyone else is rejected with 422.

A preview writes nothing and returns the planned items, unresolved variables, what still needs setup, the slots that can be rebound and anything that blocks the rollout. A staged rollout can be rebound later with { "item": "...", "slot": "branded_domain", "value": "..." } until it goes live. Go live and rollback are queued and answer 202.

* * *

Client reports and overview

A schedule is weekly or monthly, as csv or pdf, and goes to workspace members (recipient_user_ids) and to outside addresses (recipient_emails, at most 10). An outside address receives a confirmation email and gets nothing until it confirms; every report carries a link to stop it. Access is checked again whenever a report is sent. {recipient} is the handle shown in external_recipients.

GET /agency/clients/{client}/report returns the key numbers and the AI generation use of one client for the last 30 days, or for from and to. GET /agency/overview lists only the clients you hold a grant for.

* * *

Client approvals

Lists the rollouts staged in the token's own client workspace (?pending_only=1 for those waiting). Approving makes the rollout go live; rejecting discards the staged assets. Both are queued and answer 202.