Guided Meta setup

One brand, one resumable setup

Use a live API key with campaigns:read and campaigns:write. The owner claims the agent workspace once; the agent then configures the brand. Start with GET /api/v1/setup and follow next_actions. Never restart a workspace to bypass an uncertain operation.

PUT /api/v1/setup
{
  "brand_name": "Acme Studio",
  "url": "https://example.com/product",
  "description": "Simple project management for independent design studios.",
  "objective": "purchase",
  "page_mode": "create"
}

PUT is idempotent for identical content. It replaces the draft until the owner approves it. A workspace currently supports one brand and one HTTPS origin. GET returns setup.id, setup.plan_hash, setup.approval_url, next_actions, and poll_after_seconds.

Create a new Page

1. Save the initial setup with page_mode=create.
2. Upload a logo and landscape cover through POST /api/v1/assets. Use a separate persistent Idempotency-Key for each upload. PUT the raw bytes to upload_url using exactly upload_headers, then POST complete_url until the asset is ready. Up to 10 branding uploads are allowed before advertiser setup. Images must be PNG, JPEG, or WebP, at most 10 MB.
3. PUT the full setup again with logo_file_id and banner_file_id. Only this workspace’s ready assets are accepted.
4. Give setup.approval_url to the owner. They see the name, description, website, images, and public Page creation permission together. An agent cannot approve this step.
5. After consent_at is present, POST /api/v1/setup/provision with no body. This resumes durable account, branding, and Page creation steps. It does not spend money. The browser combines approval and provisioning into one owner action.
6. While page_ready=false, follow poll_after_seconds and repeat provision to refresh the Page. A resource ID alone does not mean Meta has finished provisioning.

Use an existing Page

Set page_mode=connect. Brand images are optional. After owner approval, POST provision to establish the isolated brand workspace, then POST /api/v1/setup/connect. Give authorize_url to the owner so they can grant Facebook advertising access. Never request their Facebook password.

After Facebook returns the owner to the dashboard, POST provision again. If there is exactly one ready Page it is selected automatically. If several are available, show their names and POST /api/v1/setup/page with facebook_social_account_id for the selected Page. Pages from other workspaces are never accepted. The chosen Page cannot be silently replaced later.

Install tracking while the Page provisions

As soon as the approved brand workspace exists, GET /api/v1/tracking returns the installation kit. An agent with access to the customer’s website can install it while Meta finishes the Page. Follow tracking setup. Generate creative in parallel only when the owner has authorized paid model work; creative generation uses its own gate and limits.

Owner approval contract

The signed-in owner may POST /api/v1/setup/approve:

{
  "approved_plan_hash": "<current 64-character plan_hash>",
  "authorize_managed_advertising": true,
  "authorize_page_creation": true
}

Set authorize_page_creation=true for create mode. This approval covers the brand and Page setup, not a campaign budget. If the draft changes, the old hash is rejected. After approval, brand changes require support rather than silently changing a public identity.

Resume and handle delays

Read status rather than scrape the dashboard. next_actions includes actor, label, method where applicable, URL, and blocking. Agents perform agent actions; send owner actions to the owner and stop on operator actions. A setup_in_progress response means an operation holds a short lease. Wait, read status, then resume the same setup. A timeout may have created the resource: never substitute a new workspace or operation ID. The safe provisioning retry window is 23 hours. After that, ask support to reconcile it.

ready_to_prepare means the Page and observed tracking signals are ready. It does not mean ads are delivering, funding is available, or spending has been approved. Per-advertiser purchasing capacity, service launch enablement, funding, and exact owner campaign approval still apply.

Meta provisioning, permission review, and ad review have variable timing. The goal is a short setup experience, not a guarantee of delivery within 15 minutes.