Quickstart

Get from zero to a working API call in under five minutes. By the end of this guide you will have fetched a list of workspaces, identified a funnel ID, and retrieved contacts from that funnel.

Prerequisites

• A Perspective account with Admin access
• An API key — see API Keys for how to create one

---

Step 1 — Get your API key

Every request must carry your API key in the x-perspective-api-key header. If you haven't created one yet, head to API Keys first, then come back.

Store the key in an environment variable so you don't hard-code it:

export PERSPECTIVE_API_KEY="your-api-key-here"

---

Step 2 — Discover your workspaces and funnel IDs

Call GET /v1/workspaces. The response lists every workspace you have access to, and each workspace contains its campaigns (funnels). You'll use a campaign.id as the funnelId in subsequent calls.

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();
console.log(data); // array of workspace objects

Example response:

{
  "data": [
    {
      "id": "ws_abc123",
      "name": "My Workspace",
      "campaigns": [
        { "id": "fnl_xyz789", "name": "Lead Capture Funnel", "status": "online" },
        { "id": "fnl_def456", "name": "Webinar Signup", "status": "offline" }
      ]
    }
  ]
}

Note the id value inside a campaigns entry — that is your funnelId.

---

Step 3 — Fetch contacts for a funnel

Use the funnelId from Step 2 to call GET /v1/funnels/{funnelId}/contacts. The response is paginated (page 0 by default, up to 50 contacts per page).

cURL

curl "https://api.perspective.co/v1/funnels/fnl_xyz789/contacts?limit=10" \
  -H "x-perspective-api-key: $PERSPECTIVE_API_KEY"

JavaScript

const funnelId = 'fnl_xyz789';

const response = await fetch(
  `https://api.perspective.co/v1/funnels/${funnelId}/contacts?limit=10`,
  {
    headers: {
      'x-perspective-api-key': process.env.PERSPECTIVE_API_KEY,
    },
  }
);

const { data, meta } = await response.json();
console.log(`Fetched ${data.length} of ${meta.total} contacts`);

Example response:

{
  "data": [
    {
      "id": "cnt_111",
      "email": "alice@example.com",
      "firstName": "Alice",
      "status": "converted"
    }
  ],
  "meta": {
    "total": 342,
    "page": 0,
    "limit": 10,
    "hasNext": true
  }
}

If meta.hasNext is true, increment page and repeat until it is false. See Pagination for a full loop example.

---

Next steps

• Authentication — understand how API key auth works
• Errors — status codes and error shapes
• Pagination — page through large result sets
• API Reference — full endpoint catalog
• MCP Overview — use Perspective via the Model Context Protocol