Skip to main content
Exclusions prevent Topo from sending outreach to specific people or companies, regardless of which sequences or lists they appear in. There are two separate resources: contact exclusions block an individual by email or LinkedIn URL, and account exclusions block an entire company domain. Both support permanent or time-limited exclusions and carry a structured reason code to help you report on and audit your blocklist.
Connect your CRM’s unsubscribe or opt-out webhook to the POST /v1/contact-exclusions endpoint to keep Topo’s blocklist in sync automatically. No more manually maintaining a suppression list.
Read endpoints require the exclusions:read scope. Create, update, and delete endpoints require exclusions:write.

​
Exclusion reasons

Both contact and account exclusions carry a reason field. Valid values are:
ValueDescription
UNSUBSCRIBEDPerson or account has opted out.
CONTACT_REFUSEDContact explicitly asked not to be reached.
BOUNCEDEmail hard-bounced.
WRONG_PERSONContact is not the right person at the company.
LEFT_COMPANYContact has left the company.
BAD_TIMINGNot a good time — revisit later.
OUT_OF_OFFICETemporarily unavailable.
MEETINGAlready in progress with this contact.
INTERESTEDContact has expressed interest through another channel.
COMPETITORAccount is a direct competitor.
REFERRALCame in through a referral channel; handle separately.
EXCLUDE_FROM_SEARCHSuppress from Topo’s prospecting search.
EXCLUDE_FROM_CRMImported CRM suppression.
OTHERNone of the above.
UNKNOWNReason not recorded.

​
Contact exclusions

A contact exclusion blocks a specific individual — identified by email and/or LinkedIn URL — from receiving any Topo outreach in your workspace.

​
The Contact Exclusion object

​
id
string (UUID)
required
Unique identifier for the exclusion.
​
email
string | null
Excluded email address.
​
linkedin_url
string | null
Excluded LinkedIn profile URL.
​
reason
string
Reason code for the exclusion. See Exclusion reasons above.
​
message
string | null
Free-form operator note, visible in the Topo dashboard.
​
until
string (ISO 8601) | null
Expiry timestamp. When this time is reached, the exclusion is lifted automatically. null means the exclusion is permanent.
​
created_at
string (ISO 8601)
Timestamp when the exclusion was created.
​
updated_at
string (ISO 8601)
Timestamp when the exclusion was last modified.

​
List contact exclusions

GET /v1/contact-exclusions Returns a paginated list of all contact exclusions in your workspace.

​
Query parameters

​
email
string
Exact-match filter on the excluded email address.
​
linkedin_url
string
Exact-match filter on the excluded LinkedIn URL.
​
reason
string
Filter by reason code. See Exclusion reasons for valid values.
​
created_at_after
string (ISO 8601)
Returns exclusions created strictly after this timestamp.
​
created_at_before
string (ISO 8601)
Returns exclusions created strictly before this timestamp.
​
sort_by
string
Field to sort by. One of created_at, updated_at, email, or reason.
​
page
integer
default:"1"
Page number (1-indexed).
​
size
integer
default:"10"
Results per page. Maximum 100.

​
Create a contact exclusion

POST /v1/contact-exclusions Adds an individual to your workspace blocklist. At least one of email or linkedin_url must be provided. Returns HTTP 201 Created on success.

​
Request body

​
email
string
Email address to exclude. At least one of email or linkedin_url is required.
​
linkedin_url
string
LinkedIn profile URL to exclude. At least one of email or linkedin_url is required.
​
reason
string
required
Reason code for the exclusion. Must be one of the values in Exclusion reasons.
​
message
string
Optional free-form note for your team (e.g. “Requested removal via email on 2025-03-15”).
​
until
string (ISO 8601)
Expiry timestamp for a temporary exclusion. Omit this field to create a permanent exclusion.
curl -X POST https://api.topo.io/v1/contact-exclusions \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com",
    "linkedin_url": "https://www.linkedin.com/in/jane-doe-98765",
    "reason": "UNSUBSCRIBED",
    "message": "Unsubscribed via footer link on 2025-06-10"
  }'

​
Get a contact exclusion

GET /v1/contact-exclusions/{exclusion_id} Fetches a single contact exclusion by its UUID.

​
Path parameters

​
exclusion_id
string (UUID)
required
The unique identifier of the contact exclusion.

​
Update a contact exclusion

PATCH /v1/contact-exclusions/{exclusion_id} Updates the reason, message, or expiry of an existing contact exclusion. Only fields present in the request body are modified.
To convert a temporary exclusion into a permanent one, include "until": null explicitly in the request body. Omitting until entirely leaves the existing value unchanged.

​
Path parameters

​
exclusion_id
string (UUID)
required
The unique identifier of the contact exclusion.

​
Request body

​
reason
string
Updated reason code.
​
message
string
Updated operator note.
​
until
string (ISO 8601) | null
New expiry timestamp. Pass null to make the exclusion permanent.

​
Delete a contact exclusion

DELETE /v1/contact-exclusions/{exclusion_id} Permanently removes a contact exclusion, allowing outreach to resume for that individual. Returns HTTP 204 No Content on success.
Deleting an exclusion does not automatically re-enroll the contact in any sequences. It only lifts the block; any new outreach must be initiated explicitly.

​
Path parameters

​
exclusion_id
string (UUID)
required
The unique identifier of the contact exclusion to delete.

​
Account exclusions

An account exclusion blocks an entire company domain from receiving Topo outreach, suppressing all contacts whose company_domain matches.

​
The Account Exclusion object

​
id
string (UUID)
required
Unique identifier for the exclusion.
​
domain
string | null
Excluded company domain (e.g. acme.com).
​
reason
string
Reason code for the exclusion. See Exclusion reasons above.
​
message
string | null
Free-form operator note.
​
until
string (ISO 8601) | null
Expiry timestamp. null means the exclusion is permanent.
​
created_at
string (ISO 8601)
Timestamp when the exclusion was created.
​
updated_at
string (ISO 8601)
Timestamp when the exclusion was last modified.

​
List account exclusions

GET /v1/account-exclusions Returns a paginated list of all account exclusions in your workspace.

​
Query parameters

​
domain
string
Exact-match filter on the excluded domain.
​
reason
string
Filter by reason code.
​
created_at_after
string (ISO 8601)
Returns exclusions created strictly after this timestamp.
​
created_at_before
string (ISO 8601)
Returns exclusions created strictly before this timestamp.
​
sort_by
string
Field to sort by. One of created_at, updated_at, domain, or reason.
​
page
integer
default:"1"
Page number (1-indexed).
​
size
integer
default:"10"
Results per page. Maximum 100.

​
Create an account exclusion

POST /v1/account-exclusions Adds a company domain to your workspace blocklist. All contacts whose company_domain matches will be suppressed from outreach. Returns HTTP 201 Created on success.

​
Request body

​
domain
string
required
The company domain to exclude (e.g. competitor.com).
​
reason
string
required
Reason code. Must be one of the values in Exclusion reasons.
​
message
string
Optional free-form note (e.g. “Existing customer — handle via CSM only”).
​
until
string (ISO 8601)
Expiry timestamp for a temporary exclusion. Omit for a permanent block.
curl -X POST https://api.topo.io/v1/account-exclusions \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "rival-corp.com",
    "reason": "COMPETITOR",
    "message": "Direct competitor — do not contact"
  }'

​
Get an account exclusion

GET /v1/account-exclusions/{exclusion_id} Fetches a single account exclusion by its UUID.

​
Path parameters

​
exclusion_id
string (UUID)
required
The unique identifier of the account exclusion.

​
Update an account exclusion

PATCH /v1/account-exclusions/{exclusion_id} Updates mutable fields on an existing account exclusion. Only fields present in the request body are modified.
To convert a temporary exclusion to a permanent one, pass "until": null explicitly. Omitting until entirely preserves the current value.

​
Path parameters

​
exclusion_id
string (UUID)
required
The unique identifier of the account exclusion.

​
Request body

​
reason
string
Updated reason code.
​
message
string
Updated operator note.
​
until
string (ISO 8601) | null
New expiry timestamp. Pass null to make the exclusion permanent.

​
Delete an account exclusion

DELETE /v1/account-exclusions/{exclusion_id} Permanently removes an account exclusion. Returns HTTP 204 No Content on success.

​
Path parameters

​
exclusion_id
string (UUID)
required
The unique identifier of the account exclusion to delete.