List Workspaces

Returns all workspaces and their associated campaigns (funnels) for the company tied to your API key.

GET /v1/workspaces

:::tip Discovering IDs This is the recommended starting point for any integration. The workspace and campaign IDs returned here are the IDs you pass to other endpoints such as List Contacts and Get KPI. :::

Authentication

Requires the x-perspective-api-key header. See Authentication for details.

Example request

cURL

curl "https://api.perspective.co/v1/workspaces" \
  -H "x-perspective-api-key: $PERSPECTIVE_API_KEY"

JavaScript

const response = await fetch('https://api.perspective.co/v1/workspaces', {
  headers: {
    'x-perspective-api-key': process.env.PERSPECTIVE_API_KEY,
  },
});

const { data } = await response.json();

Response

Returns { data: Workspace[] }.

Workspace object

Field	Type	Required	Description
id	string	Yes	Unique workspace identifier.
name	string	Yes	Display name of the workspace.
campaigns	object[]	Yes	Campaigns (funnels) belonging to this workspace. See WorkspaceCampaign fields.

WorkspaceCampaign fields

Each item in the campaigns array has the following fields.

Field	Type	Required	Description
id	string	Yes	Unique campaign (funnel) identifier. Use this as the funnelId in contacts and metrics endpoints.
name	string	Yes	Display name of the campaign.
status	string	Yes	Publication status. One of: "online", "offline".

Example response

{
  "data": [
    {
      "id": "ws_abc123",
      "name": "Main Workspace",
      "campaigns": [
        {
          "id": "fnl_xyz789",
          "name": "Lead Generation Funnel",
          "status": "online"
        },
        {
          "id": "fnl_def456",
          "name": "Onboarding Quiz",
          "status": "offline"
        }
      ]
    },
    {
      "id": "ws_ghi012",
      "name": "Client Projects",
      "campaigns": [
        {
          "id": "fnl_jkl345",
          "name": "Consultation Booking",
          "status": "online"
        }
      ]
    }
  ]
}

Errors

See Errors for the full list of status codes and handling guidance.

Status	Meaning
401	Missing or invalid API key.
403	Your API key does not have permission to access workspaces.
500	Internal server error.