Skip to main content

Workspaces and Campaigns

In Perspective, a workspace is an organizational container that groups related campaigns. A campaign is Perspective's internal term for a funnel — the same funnel you retrieve contacts from and query metrics against. The workspace model exists so that teams can manage multiple funnels under a shared namespace (for example, a workspace per client, per product line, or per business unit).

Why start with workspaces​

The GET /v1/workspaces endpoint is the recommended entry point for any REST API integration. It returns a single response that tells you everything you need to start working:

  • Every workspace the account has access to, with its id and name
  • Every campaign (funnel) within each workspace, with the campaign id, name, and publication status (online or offline)

The campaign id — for example, fnl_xyz789 — is the funnelId you pass to all other endpoints: contact listing, contact creation, KPI queries, chart queries, insight queries, and more. Until you have a funnelId, you cannot call most of the API. Listing workspaces is how you get those IDs.

See the Quickstart for a concrete step-by-step example that starts with GET /v1/workspaces.

The workspace and campaign objects​

A workspace response contains:

FieldTypeDescription
idstringUnique workspace identifier.
namestringHuman-readable workspace name.
campaignsarrayThe funnels inside this workspace.

Each campaign inside a workspace has:

FieldTypeDescription
idstringThe funnel ID. Use this as funnelId in contacts and metrics endpoints.
namestringCampaign display name.
statusstring"online" if published, "offline" if not yet live.

See List Workspaces for the full response schema and an example.

How IDs flow through the API​

Once you have a funnelId from the workspace response, it unlocks the rest of the API:

GET /v1/workspaces
  → campaigns[].id  (this is your funnelId)
    ├── GET /v1/funnels/{funnelId}/contacts
    ├── POST /v1/funnels/{funnelId}/contacts
    ├── GET /v1/funnels/{funnelId}/contacts/{contactId}
    ├── PUT /v1/funnels/{funnelId}/contacts/{contactId}/values
    ├── GET /v1/funnels/{funnelId}/metrics/kpis/{subtype}
    ├── GET /v1/funnels/{funnelId}/metrics/charts/{subtype}
    └── GET /v1/funnels/{funnelId}/metrics/insights/{insightId}

If you already know your funnel IDs (for example, from a previous integration or from the Perspective dashboard URL), you can call the contact and metrics endpoints directly without calling workspaces first. However, listing workspaces is the most reliable way to discover IDs programmatically.

Campaigns vs funnels: same thing, different name​

You will see both terms in this documentation. The REST API uses "funnel" in its route paths and the id prefix (fnl_). The workspace endpoint uses "campaign" to match Perspective's internal organizational model. These refer to the same entity: a funnel ID and a campaign ID are the same value.

Workspaces in the MCP​

The MCP server exposes a tool for listing workspaces, which AI agents use to orient themselves before working with a specific funnel or campaign. See MCP Workspaces tools for details.

Next steps​