Skip to main content
The Topo API is a REST API that lets you integrate your tools and workflows directly with your Topo workspace. Every resource is available over HTTPS, every request and response body is JSON, and every list response follows the same paginated envelope so you always know what to expect.

​
Base URL

All endpoints are served under a single versioned base URL: 
https://api.topo.io/v1

​
What you can do

  • Sync contacts — create, update, and query contacts inside your workspace.
  • Manage exclusions — add or remove contact and company suppression rules.
  • Control sequences — read sequences and enroll or remove contacts.
  • Read activities — pull a time-ordered stream of outreach events.
  • Manage contact & account lists — create and populate segmentation lists.
  • Subscribe to webhooks — register endpoints to receive real-time event payloads.
  • Manage tasks — read and update tasks associated with your outreach.

​
Versioning

The major API version lives in the URL path (/v1). Topo follows these rules to keep your integration stable:
Change typeShips as
New endpoint, new optional field, new response field, new enum valueAdditive change in /v1 — no action needed on your side
Removed or renamed endpoint, field, or scope; changed field type; changed HTTP statusBreaking change, ships as /v2
You should write your client to ignore unknown fields in responses. Topo may add new fields to any response object at any time within /v1.

​
Quick start

Once you have an API key (see Authentication), make your first request to confirm your credentials and see which scopes your key carries: 
curl https://api.topo.io/v1/me \
  -H "Authorization: Bearer topo_xxxxxxxxxxxx"

{
  "id": "018f1a2b-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "organization_id": "018e9d8c-7b6a-7f5e-4d3c-2b1a0f9e8d7c",
  "name": "My Integration Key",
  "key_prefix": "topo_xxxx",
  "scopes": ["contacts:read", "sequences:read"],
  "created_at": "2024-11-01T09:00:00Z",
  "last_used_at": "2025-01-15T14:23:11Z"
}

​
Explore the docs

Authentication

Learn how to create API keys, pass them in requests, and scope them to least-privilege access.

Pagination & Filtering

Understand the standard list envelope, page through large result sets, and filter records.

Errors & Rate Limits

Decode error responses, handle rate limiting gracefully, and debug with request IDs.

Contacts

Create, read, update, and delete contacts in your workspace.