Public API

API overview

GET-only, read-only, workspace-scoped Public API for reports, Signals, accounts, stakeholders, website activity and targeting summaries. Get the server URL when creating an access token in Settings > API Tokens. Replace the non-working server placeholder with the origin of that URL (scheme and host, without /api/v1/public); the specification already includes /api/v1/public in each route path. Configure the generated token as the bearer credential. The token determines workspace scope.

Base URL: https://server-url-from-token-page.endpoint

Version: 1.2.0. Published endpoints: 11.

DOE API Token User Guide

Use a DOE API token to read reports, signals, accounts, stakeholders, website activity and targeting summaries from one workspace. The token determines which workspace you can access. Send it in the Authorization header; the Public API does not create, update or delete data.

Before you create a token

• Know which client or workflow will use the token.
• Know who owns that client or workflow.
• Choose an expiry that fits the task: one month by default, with a maximum of one year.
• Decide where the token will be stored after creation.
• Each workspace can have up to two unexpired API tokens. Use separate tokens for unrelated clients where possible, and revoke unused ones before creating replacements.
• Do not reuse one token across unrelated consumers.
• Store the token in a password manager or secret manager immediately.

Quick start

1. Open the workspace that owns the API data.
2. Go to Settings.
3. Open API Tokens.
4. Click Generate token.
5. Confirm the Space ID.
6. Select API Space Read Only.
7. Copy the Public API server URL shown when creating the access token. Use this URL to configure your client.
8. Choose an expiry date. If you leave it unset, the token expires after one month; the maximum lifetime is one year.
9. Click Generate.
10. Copy the token immediately from the success dialog and store it safely.

Safety checklist

• Use separate tokens for unrelated clients where possible, within the workspace's two-token limit.
• Choose the shortest practical expiry and plan renewal before it is reached.
• Save the token immediately because the secret is shown only once.
• Store tokens in a secure secret manager or password manager.
• Rotate tokens after suspected exposure. If the owner changes, have the new owner issue a new token.
• Revoke tokens you no longer need.
• Periodically review active tokens in the API Tokens table.

Reports

Read-only workspace reports.

curl "https://server-url-from-token-page.endpoint/api/v1/public/reports?type=AMPS&duration=ALL_TIME&take=10&skip=0&sortKey=overall.clicks&sortOrder=-1" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-reports"

{
  "data": [],
  "metadata": {
    "count": 0
  }
}

Signals

Read-only paginated workspace Signals with exact counts and compact references.

curl "https://server-url-from-token-page.endpoint/api/v1/public/signals?take=10&skip=0&type=ENGAGED%2CVISIT&duration=LAST_30_DAYS" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439041",
      "createdAt": "2026-07-30T10:15:00.000Z",
      "type": "ENGAGED",
      "accountId": "507f1f77bcf86cd799439011",
      "stakeholderId": "507f1f77bcf86cd799439031",
      "lastClickDate": "2026-07-30T10:10:00.000Z",
      "lastClickTitle": "Product overview",
      "clicks": 3,
      "impressions": 18
    },
    {
      "id": "507f1f77bcf86cd799439042",
      "createdAt": "2026-07-29T08:00:00.000Z",
      "type": "VISIT",
      "accountId": "507f1f77bcf86cd799439011",
      "leadId": "507f1f77bcf86cd799439051",
      "lastVisitDate": "2026-07-29T07:55:00.000Z",
      "visits": 2,
      "locations": [
        "Stockholm, Sweden"
      ],
      "newLead": true
    }
  ],
  "references": {
    "accountsById": {
      "507f1f77bcf86cd799439011": {
        "id": "507f1f77bcf86cd799439011",
        "name": "Example account",
        "linkedIn": "https://www.linkedin.com/company/example",
        "website": "https://www.example.com",
        "owners": [
          {
            "id": "507f1f77bcf86cd799439061",
            "name": "Example owner"
          }
        ]
      }
    },
    "stakeholdersById": {
      "507f1f77bcf86cd799439031": {
        "id": "507f1f77bcf86cd799439031",
        "name": "Ada Lovelace",
        "position": "Chief Scientist",
        "linkedIn": "https://www.linkedin.com/in/ada-lovelace",
        "email": "ada@example.com"
      }
    },
    "leadsById": {
      "507f1f77bcf86cd799439051": {
        "id": "507f1f77bcf86cd799439051",
        "name": "Visitor company"
      }
    }
  },
  "metadata": {
    "count": 2,
    "insights": {
      "typeDistribution": [
        {
          "type": "ENGAGED",
          "label": "Engaged",
          "count": 1,
          "percentage": 33.3
        },
        {
          "type": "VISIT",
          "label": "Website visit",
          "count": 2,
          "percentage": 66.7
        }
      ],
      "uniqueAccounts": 1,
      "uniqueStakeholders": 1,
      "engagedStakeholders": 1,
      "accountsWithEngagedStakeholders": 1,
      "visitedAccounts": 1,
      "newLeadSignals": 1,
      "latestSignalAt": "2026-07-30T10:10:00.000Z",
      "topAccounts": [
        {
          "accountId": "507f1f77bcf86cd799439011",
          "signalCount": 2,
          "latestSignalAt": "2026-07-30T10:10:00.000Z"
        }
      ]
    }
  },
  "pagination": {
    "skip": 0,
    "take": 10,
    "returned": 2,
    "hasMore": false
  }
}

Accounts

Read-only account listing and detail operations.

curl "https://server-url-from-token-page.endpoint/api/v1/public/accounts?take=10&skip=0&project=crm%2CtargetingActivated" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Example account",
      "status": "Prospects",
      "industry": "Software",
      "marketSegment": "Enterprise",
      "targeting": "IN_TARGETING",
      "owners": [
        {
          "id": "507f1f77bcf86cd799439021",
          "name": "Example owner"
        }
      ],
      "targetingActivated": {
        "individual": "YES",
        "linkedIn": "NO",
        "ip": "YES",
        "geo": "NONE"
      },
      "crm": [
        {
          "provider": "hubspot",
          "objectId": "123456789",
          "objectUrl": "https://app.hubspot.com/contacts/123/company/123456789",
          "mappedAt": "2026-08-10T09:00:00Z"
        }
      ]
    }
  ],
  "metadata": {
    "count": 1,
    "industries": [
      "Software"
    ]
  },
  "pagination": {
    "skip": 0,
    "take": 10,
    "returned": 1,
    "hasMore": false
  }
}

curl "https://server-url-from-token-page.endpoint/api/v1/public/accounts/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Stakeholders

Read-only stakeholder listing and detail operations.

curl "https://server-url-from-token-page.endpoint/api/v1/public/stakeholders?take=10&skip=0&project=crm%2Ctype%2CtrafficLight" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439012",
      "name": "Ada Lovelace",
      "accountId": "507f1f77bcf86cd799439011",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "position": "Chief Scientist",
      "email": "ada@example.com",
      "linkedIn": "https://www.linkedin.com/in/ada-lovelace",
      "targeting": "IN_TARGETING",
      "type": [
        "Decision Maker"
      ],
      "trafficLight": "GREEN",
      "crm": [
        {
          "provider": "salesforce",
          "objectId": "003000000000001AAA",
          "objectUrl": "https://example.my.salesforce.com/lightning/r/Contact/003000000000001AAA/view",
          "mappedAt": "2026-08-11T10:00:00Z"
        }
      ]
    }
  ],
  "references": {
    "accountsById": {
      "507f1f77bcf86cd799439011": {
        "id": "507f1f77bcf86cd799439011",
        "name": "Example account",
        "status": "Prospects",
        "industry": "Software",
        "marketSegment": "Enterprise",
        "targeting": "IN_TARGETING",
        "owners": [
          {
            "id": "507f1f77bcf86cd799439021",
            "name": "Example owner"
          }
        ]
      }
    }
  },
  "metadata": {
    "count": 1
  },
  "pagination": {
    "skip": 0,
    "take": 10,
    "returned": 1,
    "hasMore": false
  }
}

curl "https://server-url-from-token-page.endpoint/api/v1/public/stakeholders/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Website

Read-only website visits, journeys, top pages, and aggregate insights.

curl "https://server-url-from-token-page.endpoint/api/v1/public/website/visits?leadId=507f1f77bcf86cd799439013&take=10&skip=0" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": [
    {
      "id": "visit-1",
      "startedAt": "2026-07-30T10:15:00Z",
      "visitLength": 240,
      "leadId": "507f1f77bcf86cd799439013",
      "accountId": "507f1f77bcf86cd799439011",
      "visitRoute": [
        {
          "pagePath": "/pricing",
          "timeOnPage": 120
        }
      ]
    }
  ],
  "references": {
    "accountsById": {
      "507f1f77bcf86cd799439011": {
        "id": "507f1f77bcf86cd799439011",
        "name": "Example account",
        "status": "Prospects",
        "industry": "Software",
        "marketSegment": "Enterprise",
        "targeting": "IN_TARGETING",
        "owners": [
          {
            "id": "507f1f77bcf86cd799439021",
            "name": "Example owner"
          }
        ]
      }
    },
    "leadsById": {
      "507f1f77bcf86cd799439013": {
        "id": "507f1f77bcf86cd799439013",
        "name": "Example visitor"
      }
    }
  },
  "metadata": {
    "count": 1
  },
  "pagination": {
    "skip": 0,
    "take": 10,
    "returned": 1,
    "hasMore": false
  }
}

curl "https://server-url-from-token-page.endpoint/api/v1/public/website/accounts?type=ALL_ACCOUNTS&duration=LAST_3_MONTHS&sort=VISITS&take=10&skip=0" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": [
    {
      "leadId": "507f1f77bcf86cd799439013",
      "accountId": "507f1f77bcf86cd799439011",
      "lastVisitAt": "2026-07-30T10:15:00Z",
      "visits": 4,
      "pageViews": 9,
      "targeting": "IN_TARGETING"
    }
  ],
  "references": {
    "accountsById": {
      "507f1f77bcf86cd799439011": {
        "id": "507f1f77bcf86cd799439011",
        "name": "Example account",
        "status": "Prospects",
        "industry": "Software",
        "marketSegment": "Enterprise",
        "targeting": "IN_TARGETING",
        "owners": [
          {
            "id": "507f1f77bcf86cd799439021",
            "name": "Example owner"
          }
        ]
      }
    },
    "leadsById": {
      "507f1f77bcf86cd799439013": {
        "id": "507f1f77bcf86cd799439013",
        "name": "Example account"
      }
    }
  },
  "metadata": {
    "count": 1,
    "accounts": 1,
    "type": "ALL_ACCOUNTS"
  },
  "pagination": {
    "skip": 0,
    "take": 10,
    "returned": 1,
    "hasMore": false
  }
}

curl "https://server-url-from-token-page.endpoint/api/v1/public/website/top-pages?accountId=507f1f77bcf86cd799439011&duration=LAST_30_DAYS&take=10&skip=0" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": [
    {
      "pageKey": "/pricing",
      "pagePath": "/pricing",
      "pageViews": 10,
      "sessions": 7,
      "totalTimeOnPage": 800,
      "avgTimeOnPage": 80,
      "totalVisitLength": 900,
      "avgVisitLength": 90
    }
  ],
  "metadata": {
    "count": 1,
    "timezone": "Europe/Stockholm",
    "duration": "LAST_30_DAYS"
  },
  "pagination": {
    "skip": 0,
    "take": 10,
    "returned": 1,
    "hasMore": false
  }
}

curl "https://server-url-from-token-page.endpoint/api/v1/public/website/insights?type=TARGETED_ACCOUNTS&duration=LAST_30_DAYS" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": {
    "targetingScope": "TARGETED_ACCOUNTS",
    "targetedCount": 2,
    "nonTargetedCount": 0,
    "accounts": 2,
    "uniqueAccounts": 2,
    "uniqueLeads": 2,
    "visits": 12,
    "pageViews": 30,
    "averageVisitDuration": 180,
    "countries": [
      {
        "group": "SE",
        "count": 2
      }
    ],
    "dailyTrackingRecords": [
      {
        "date": "2026-07-30",
        "visits": 12,
        "pageViews": 30
      }
    ],
    "industries": [
      {
        "group": "Software",
        "count": 2
      }
    ],
    "sources": [
      {
        "group": "direct",
        "count": 8
      }
    ]
  }
}

Targeting

Read-only workspace targeting summary.

curl "https://server-url-from-token-page.endpoint/api/v1/public/targeting-summary" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Request-Id: postman-{{$guid}}" \
  -H "X-Client-Name: postman-public-api"

{
  "data": {
    "accountsInTargetingCount": 10,
    "stakeholdersInTargetingCount": 25,
    "accountsHQCountryMap": [
      {
        "group": "SE",
        "count": 6
      }
    ],
    "accountsTypeMap": [
      {
        "group": "Prospect",
        "count": 10
      }
    ]
  }
}

Frequently asked questions

I closed the success dialog without copying the token. Can I get it back?

No. The secret token value is shown only once. Create a new token or rotate the existing one if you still need access.

Which endpoint should I use?

Get the Public API server URL when creating an access token in Settings > API Tokens. Copy the URL shown for your workspace and append the route you need, such as /reports. Do not add /api/v1/public a second time.

Where can I review the available APIs?

Use the API guide on this page. It groups supported Public API endpoints by product area and shows parameters, request examples, and response shapes without needing separate files.

Which header should I send?

Use Authorization: Bearer <token>. This is the supported authentication header for API tokens.

What can the read-only API token access?

It can call supported routes under /api/v1/public for the workspace that issued the token. It does not create, edit, delete, or approve workspace data.

How should I page through long result sets?

Use the documented take and skip query parameters where they are available. Keep pages small, process one page at a time, and avoid running large reporting jobs in a tight loop.

How do I handle a 429 rate-limit response?

Read the Retry-After header, wait for that duration, and retry with lower request volume. For scheduled jobs, spread calls over time instead of starting every report at once.

Can I use X-MCP-Token or ?token= with an API token?

No. The Public API accepts only Authorization: Bearer <token> with an API Space Read Only token. The header and URL alternatives described in the MCP guide apply only to MCP.

Can one token be shared by multiple tools?

Prefer separate tokens for unrelated clients so you can manage access independently. Each workspace can have at most two unexpired API tokens; expired tokens do not use a slot. Revoke unused tokens when you need room for a new integration.

What is the difference between rotate and revoke?

Rotate replaces the secret with a new one so the client can continue after you update it. Revoke disables the token completely.

What happens when a token expires?

An expired token cannot authenticate. The owner can rotate it with a new expiry, or create a new token, if a workspace token slot is available. A token also stops working if its owner loses access to the workspace.

What happens if I leave expiry empty?

The token expires after one month. Every new or rotated token has an expiry, and you cannot request more than one year.

What should I include when asking for support?

Share the route, method, approximate time, response code, and X-Request-Id if available. Do not send the full bearer token, screenshots containing secrets, or copied Authorization headers.

Do the new MCP write tools also work through the Public API?

No. The Public API remains read-only and uses API Space Read Only tokens. MCP's account/stakeholder write tools require a separate MCP Space Read Write token and the /mcp endpoint. The two types of token are not interchangeable.

How do I supply filters and request extra fields?

Use each endpoint's documented URL query parameters, not MCP's JSON arguments. Send supported multi-value filters once as comma-separated values. On supported endpoints, project requests optional fields such as CRM references without changing which rows match.

How should I choose a report or comparison period?

Read the report's supported parameters and date rules before calling /reports. SMP summarizes activity by media technique, SMPC compares adjacent equal-length periods, and STAM ranks account gains or declines. IP and GEO values may remain cumulative or be unavailable for period comparisons; do not treat them as period totals.