Count which selected prospects a bulk action applies to
curl --request POST \
--url https://api.snowseo.com/v3/outreach/prospects/bulk-preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"selection": {
"mode": "ids",
"ids": [
"<string>"
]
},
"teamId": "<string>",
"reason": "<string>",
"terms": [
"<string>"
]
}
'import requests
url = "https://api.snowseo.com/v3/outreach/prospects/bulk-preview"
payload = {
"selection": {
"mode": "ids",
"ids": ["<string>"]
},
"teamId": "<string>",
"reason": "<string>",
"terms": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
selection: {mode: 'ids', ids: ['<string>']},
teamId: '<string>',
reason: '<string>',
terms: ['<string>']
})
};
fetch('https://api.snowseo.com/v3/outreach/prospects/bulk-preview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.snowseo.com/v3/outreach/prospects/bulk-preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'selection' => [
'mode' => 'ids',
'ids' => [
'<string>'
]
],
'teamId' => '<string>',
'reason' => '<string>',
'terms' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.snowseo.com/v3/outreach/prospects/bulk-preview"
payload := strings.NewReader("{\n \"selection\": {\n \"mode\": \"ids\",\n \"ids\": [\n \"<string>\"\n ]\n },\n \"teamId\": \"<string>\",\n \"reason\": \"<string>\",\n \"terms\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.snowseo.com/v3/outreach/prospects/bulk-preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"selection\": {\n \"mode\": \"ids\",\n \"ids\": [\n \"<string>\"\n ]\n },\n \"teamId\": \"<string>\",\n \"reason\": \"<string>\",\n \"terms\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.snowseo.com/v3/outreach/prospects/bulk-preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"selection\": {\n \"mode\": \"ids\",\n \"ids\": [\n \"<string>\"\n ]\n },\n \"teamId\": \"<string>\",\n \"reason\": \"<string>\",\n \"terms\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"eligibility": {
"selected": 123,
"eligible": 123,
"skipped": 123,
"byReason": {}
}
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}Prospects
Bulk prospect actions
Preview, delete, block, find people at, or re-check many outreach prospects at once.
POST
/
v3
/
outreach
/
prospects
/
bulk-preview
Count which selected prospects a bulk action applies to
curl --request POST \
--url https://api.snowseo.com/v3/outreach/prospects/bulk-preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"selection": {
"mode": "ids",
"ids": [
"<string>"
]
},
"teamId": "<string>",
"reason": "<string>",
"terms": [
"<string>"
]
}
'import requests
url = "https://api.snowseo.com/v3/outreach/prospects/bulk-preview"
payload = {
"selection": {
"mode": "ids",
"ids": ["<string>"]
},
"teamId": "<string>",
"reason": "<string>",
"terms": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
selection: {mode: 'ids', ids: ['<string>']},
teamId: '<string>',
reason: '<string>',
terms: ['<string>']
})
};
fetch('https://api.snowseo.com/v3/outreach/prospects/bulk-preview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.snowseo.com/v3/outreach/prospects/bulk-preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'selection' => [
'mode' => 'ids',
'ids' => [
'<string>'
]
],
'teamId' => '<string>',
'reason' => '<string>',
'terms' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.snowseo.com/v3/outreach/prospects/bulk-preview"
payload := strings.NewReader("{\n \"selection\": {\n \"mode\": \"ids\",\n \"ids\": [\n \"<string>\"\n ]\n },\n \"teamId\": \"<string>\",\n \"reason\": \"<string>\",\n \"terms\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.snowseo.com/v3/outreach/prospects/bulk-preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"selection\": {\n \"mode\": \"ids\",\n \"ids\": [\n \"<string>\"\n ]\n },\n \"teamId\": \"<string>\",\n \"reason\": \"<string>\",\n \"terms\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.snowseo.com/v3/outreach/prospects/bulk-preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"selection\": {\n \"mode\": \"ids\",\n \"ids\": [\n \"<string>\"\n ]\n },\n \"teamId\": \"<string>\",\n \"reason\": \"<string>\",\n \"terms\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"eligibility": {
"selected": 123,
"eligible": 123,
"skipped": 123,
"byReason": {}
}
}{
"success": true,
"error": "<string>",
"code": "<string>",
"message": "<string>",
"reference": "<string>"
}Every bulk action takes a
Each call processes one batch of eligible prospects and returns
selection and works through it in batches:
selectionis either{ mode: "ids", ids: [prospectId, ...] }or{ mode: "all", filters: { ready?, search?, groups? }, excludedIds: [...] }(every prospect matching the filters, minus the excluded ids).- Call
POST /v3/outreach/prospects/bulk-previewwith theselectionand anaction(delete,block,find-peopleorrecheck) first. It changes nothing and returnseligibility:{ selected, eligible, skipped, byReason }, e.g. sites skipped because a search is already running.
| Action | Endpoint | Rows per call | Notes |
|---|---|---|---|
| Delete | POST /v3/outreach/prospects/bulk-delete | 50 | Removes the rows and blocks their sites. A creator-platform prospect with no known creator is removed without a block. |
| Block | POST /v3/outreach/prospects/bulk-block | 50 | Body reason (up to 200 characters). An ordinary site is blocked by domain, so other rows on that domain are removed too. A creator-platform prospect blocks only that creator. |
| Find people | POST /v3/outreach/prospects/bulk-find-people | 10 | Body terms (3-25 distinct job titles; omit for the defaults, 400 for overlapping terms). 5 AI credits per site, 402 when you lack credits, refunded when a site yields nobody new. Skipped at no cost: searches already running, creator platforms, opportunities that are not earned by writing to someone, and sites that already link to you. |
| Re-check links | POST /v3/outreach/prospects/bulk-recheck | 10 | One page crawl per page, 402 when you lack page audits. Sites already being checked are skipped. |
{ success, succeeded, failed, nextCursor, eligibility, results }. While nextCursor is not null, call again with the same selection and afterId set to nextCursor. results has one entry per prospect with id, success and error when it failed. Find people adds creditsCharged, re-check adds pages, and block adds blocked and removed.
Find people and re-check run in the background. Poll Outreach Prospects while a site’s status is finding_people or its analysis is rechecking, then read Outreach Contacts or linkStatus. Finding people does not buy email addresses; use Bulk people actions.
POST /v3/outreach/prospects/selection returns the prospect rows a selection matches, for reads too large for a query string.
For a single prospect, use Delete prospect. To reverse a block, see Unblock a domain.Authorizations
bearerAuthapiKey
Your SnowSEO API key (sk_...).
Body
application/json
- Option 1
- Option 2
Show child attributes
Show child attributes
The bulk action to count eligible rows for.
Available options:
delete, block, find-people, recheck Why they were blocked, shown in the blocked list.
Maximum string length:
200Job titles to search for, matched as substrings and OR'd together - 'editor' finds 'Managing Editor'. Between 3 and 25 distinct terms; omit to use a sensible default covering editorial, SEO, marketing and owners.
Required array length:
3 - 25 elementsResponse
Default Response
Show child attributes
Show child attributes
Was this page helpful?

