> ## Documentation Index
> Fetch the complete documentation index at: https://snowseo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Prospects
> Find sites worth pitching for a backlink, manage the list, and check whether the links went live.
A **prospect** is one website that could link to you, plus the specific page the link would go on. This group covers finding them, curating the list, and re-checking earned links.
Backlink Outreach is in **beta**. Endpoints live under `/v3/outreach` and every request is scoped to the brand your API key belongs to, so there is no `teamId` to pass. See [Authentication](/docs/api-reference/authentication).
Several of these endpoints spend credits. Every one that does says so below. Background work is tracked through the prospect and mailbox statuses, without exposing queue job IDs.
***
## List prospects
`GET /outreach/prospects`
Every prospect for the brand, most recently active first, with the page it would be pitched about, its Domain Rating, contact counts and pipeline stage. Activity on a prospect's people or pages moves it up the list. This is the starting point for any outreach question.
**Query parameters**
| Parameter | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `status` | Filter by how far the contact search got: `pending`, `finding_people`, `people_found`, `no_people`, `failed` |
| `source` | Filter to prospects with at least one page from this discovery source: `query-expansion`, `keyword-serp`, `ai-citation`, `manual` |
**Key fields on each prospect**
| Field | What it tells you |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `domain` | The site |
| `targetPage` | The page the pitch is about - URL, title, page type, and the search that surfaced it. `null` for a hand-added bare domain |
| `domainRating` | Domain Rating, 0-100. `null` until fetched |
| `opportunity` | The ask: `fix-broken-link`, `ask-for-link`, `offer-alternative`, `get-listed`, `pitch`, or `already-linked` |
| `linkStatus` | What the crawl found about your domain on their pages: `linked`, `unlinked`, `broken`, `absent`, or `unknown` |
| `worth` / `worthBand` | What the link is worth, 0-100 and a band |
| `odds` / `oddsBand` | How likely the ask is to land: `high`, `medium`, `long` |
| `reasons` / `nextStep` | Evidence behind the recommendation and the suggested next action |
| `actionable` | `false` when there is nothing left to pitch or the site is a direct competitor |
| `relationship` | Who publishes it: `publisher`, `vendor_adjacent`, `directory`, `community`, `competitor`, `unknown` |
| `linkPlay` | How the link is actually earned: `outreach`, `creator`, `self-serve`, `community` |
| `playbook` | Step-by-step instructions, present only when `linkPlay` is not `outreach` |
| `outreachStage` | Pipeline stage: `not_started`, `people_found`, `enriched`, `contacted`, `negotiating`, `won` |
| `peopleCount` | People found at the site |
| `emails` | Contact addresses found so far |
| `doNotContact` | Excluded from sending, but still on the list |
The response also carries `discoveryStatus`, `mentionCheckStatus` and `relationshipSweepStatus`. Keep polling while any is `running`. Each prospect's `status` reports contact search progress; `analysis: "rechecking"` reports a link re-check in progress.
The API returns activity order. You can sort the returned rows by `odds` for quick wins or by `worth` for high-value targets. Those signals can disagree: a valuable link may still be unlikely to earn.
***
## Find new prospects
`POST /outreach/discover/run`
[Open the request and response reference](/docs/api-reference/endpoints/outreach-find-prospects).
Searches for pages that mention your brand, your category or your competitors and turns them into prospects. Takes no arguments - the search plan is built from your brand name and website, so both must be set in brand settings first.
Runs in the background. Poll the prospects list while its discovery, mention-check or relationship-sweep status is `running`.
**Response**
| Field | Description |
| ---------------- | -------------------------------------------------------------- |
| `status` | `running` while discovery is underway |
| `creditsCharged` | Credits spent on this search |
| `alreadyRunning` | `true` when a search was already in flight; nothing is charged |
**Costs 25 AI credits.** Your brand's very first prospect list is generated automatically and free of charge the first time the prospects list is read.
A `409` means every search angle has been used recently and a new pass would return the same sites. Track more keywords or add a topic cluster, then try again. Nothing is charged. A `503` means the search is briefly unavailable and is safe to retry; a `402` means you are out of credits.
***
## Add prospects
`POST /outreach/prospects`
Add sites you already know are worth pitching. Discovery finds prospects on its own - use this for the ones you bring yourself.
**Body**
| Field | Description |
| --------- | ---------------------------------------------------------------- |
| `domain` | A single domain or full URL. Shorthand for a one-entry `domains` |
| `domains` | Array of domains or full URLs, up to 200 per call |
Pass the **full URL of the page you want the link on** whenever you know it: the site becomes the prospect and that page becomes what the pitch is written about. A bare domain or a home page records no page, which leaves the draft writer with nothing specific to point at.
This endpoint never fails as a whole. Unparseable entries are counted in `invalid`, domains already on the list in `skipped`, and `prospects` carries only the rows actually created. New prospects start with no contacts - run [Find people](/docs/api-reference/endpoints/outreach-contacts#find-people) next.
***
## Delete a prospect
`DELETE /outreach/prospects/{id}`
Removes one prospect. It can be found again by a future search - use **Block** below to keep it out for good.
***
## Block prospects
`POST /outreach/prospects/block`
Removes prospects and stops them ever returning from discovery. Use this for sites you do not want to be associated with, or anyone who has asked not to be contacted.
**Body**
| Field | Description |
| ------------- | ------------------------------------------------------------- |
| `prospectIds` | Prospect IDs to block, up to 50 |
| `reason` | Optional note shown in the blocked list, up to 200 characters |
An ordinary site is blocked by **domain**, so `removed` can be higher than the number of IDs you sent when that site has several prospect rows. A prospect on a creator platform (a YouTube channel, a Substack) blocks only that creator and leaves the rest of the platform discoverable.
### Unblock a domain
`DELETE /outreach/prospects/blocked/{domain}`
Removes the block so the site can be discovered again. Pass `creatorHandle` as a query parameter to unblock a single creator rather than the whole domain.
***
## Set a prospect's relationship
`PATCH /outreach/prospects/relationship`
Corrects who SnowSEO thinks publishes a site. The common use is rescuing a prospect wrongly filed as a competitor.
**Body**: `prospectIds`, and `relationship` - one of `publisher`, `vendor_adjacent`, `directory`, `community`, `competitor`.
A decision made here is final: it outranks anything the classifier later concludes.
***
## Override a prospect's stage
`PATCH /outreach/prospects/{id}/stage`
Pins a prospect to a pipeline stage, or clears the override.
**Body**: `stage` - one of `contacted`, `negotiating`, `won`, or `null` to clear.
The stage is normally derived from real signals - contacts found, mail sent, replies received, links confirmed - so only override it to record something that happened off-platform. A prospect cannot be moved backwards, and an override never hides a reply or a confirmed link that arrives later.
***
## Choose which page to pitch
`PATCH /outreach/prospects/{id}/target-page`
Picks a different page as the one the pitch is about.
**Body**: `mentionId` - the ID of one of the prospect's pages, or `null` to go back to the automatic choice.
***
## List a prospect's pages
`GET /outreach/prospects/{id}/pages`
Every page found on one site, with its link status, page type, the query that surfaced it and where it ranked. Paginate with `limit` and `offset`.
## List every page
`GET /outreach/prospects/pages`
The same rows across all prospects, one per page, for export. Cap with `limit`. The response flags when the ceiling was hit so you never hand over a quietly short file.
***
## Re-check links
`POST /outreach/prospects/recheck`
Re-crawls a prospect's pages to see whether the backlink went live, and updates `linkStatus`. A confirmed link moves the prospect to **won** on its own.
**Body**: `prospectIds`, up to 50.
Runs in the background. The response includes the accepted `prospectIds`. Poll the prospects list while those rows have `analysis: "rechecking"`, then read `linkStatus` for the verdict. No job ID or separate job-status endpoint is needed.
**Costs one page crawl per page read.** Run it after a reply suggests the link was added, not speculatively.
To have this run on a schedule instead, switch on auto re-checking in [Outreach automation](/docs/api-reference/endpoints/outreach-sending#outreach-automation).
***
## Rate limits
Outreach endpoints are individually rate limited, with the tightest limits on the ones that spend money - discovery, enrichment, re-checks and sending. A `429` carries a `Retry-After` header. Back off rather than retrying immediately.
## OpenAPI
````yaml GET /v3/outreach/prospects
openapi: 3.0.0
info:
title: SnowSEO API
description: API documentation for SnowSEO
version: 1.0.0
servers:
- url: https://api.snowseo.com
description: Production server
security: []
tags:
- name: Keywords
description: Keyword research and suggestion end-points
- name: Onboarding
description: Brand onboarding and strategy end-points
- name: Brands
description: Brand management end-points
- name: Organizations
description: Organization and member end-points
- name: Integrations
description: Google Search Console and other integrations
- name: Utilities
description: Common utility end-points like screenshots and uploads
externalDocs:
url: https://snowseo.com/docs
description: Find more info here
paths:
/v3/outreach/prospects:
get:
tags:
- Outreach
summary: List backlink outreach prospects
description: >-
Sites worth pitching for a backlink, with the page each one would be
pitched about, its Domain Rating, how many contacts have been found and
where it sits in the pipeline. This is the starting point for any
outreach question.
operationId: listOutreachProspects
parameters:
- schema:
type: string
enum:
- pending
- finding_people
- people_found
- no_people
- failed
in: query
name: status
required: false
description: Filter by how far the contact search has got for each prospect.
- schema:
type: string
in: query
name: source
required: false
description: >-
Filter to prospects with at least one page from this discovery
source.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
prospects:
type: array
items:
type: object
properties:
id:
type: string
domain:
type: string
source:
type: string
status:
type: string
isNew:
type: boolean
createdAt:
type: string
updatedAt:
type: string
lastActivityAt:
type: string
description: >-
Latest activity on this prospect or its people,
pages, messages, and emails. List order is
descending by this time.
targetPage:
type: object
properties:
id:
type: string
url:
type: string
title:
type: string
nullable: true
source:
type: string
matchedQuery:
type: string
nullable: true
pageType:
type: string
nullable: true
linkStatus:
type: string
nullable: true
topicalFit:
type: number
nullable: true
additionalProperties: true
nullable: true
description: >-
The specific page the pitch is about, or null for a
bare domain.
domainRating:
type: number
nullable: true
opportunity:
type: string
description: >-
The concrete backlink ask, such as fixing a broken
link or being added to a list.
opportunityDetails:
type: object
properties:
code:
type: string
label:
type: string
description:
type: string
strength:
type: number
action:
type: string
additionalProperties: true
lane:
type: object
properties:
code:
type: string
label:
type: string
action:
type: string
hint:
type: string
channel:
type: string
additionalProperties: true
linkStatus:
type: string
nullable: true
linkEvidence:
type: string
nullable: true
reasons:
type: array
items:
type: string
description: >-
Observed evidence behind the recommendation, most
important first.
nextStep:
type: string
description: Suggested next action in plain language.
worth:
type: number
description: >-
Estimated link value from 0 to 100, separate from
the odds of earning it.
worthBand:
type: string
enum:
- strong
- decent
- low
worthDetails:
type: object
properties:
score:
type: number
band:
type: string
label:
type: string
additionalProperties: true
odds:
type: number
description: >-
Estimated chance of earning the link from 0 to 100,
separate from link value.
oddsBand:
type: string
enum:
- high
- medium
- long
oddsDetails:
type: object
properties:
score:
type: number
band:
type: string
label:
type: string
additionalProperties: true
relationship:
type: string
relationshipDetails:
type: object
properties:
code:
type: string
label:
type: string
description:
type: string
additionalProperties: true
actionable:
type: boolean
description: >-
False when the link is already live or the publisher
is a direct competitor.
linkPlay:
type: string
playbook:
type: object
properties:
play:
type: string
title:
type: string
summary:
type: string
steps:
type: array
items:
type: string
additionalProperties: true
nullable: true
outreachStage:
type: string
contactReadiness:
type: object
properties:
code:
type: string
label:
type: string
description:
type: string
rank:
type: number
channel:
type: string
additionalProperties: true
peopleCount:
type: number
pageCount:
type: number
emails:
type: array
items:
type: object
properties:
id:
type: string
email:
type: string
name:
type: string
nullable: true
role:
type: string
nullable: true
verifiedStatus:
type: string
confidence:
type: number
isPrimary:
type: boolean
additionalProperties: true
analysis:
type: string
nullable: true
doNotContact:
type: boolean
additionalProperties: true
discoveryStatus:
type: string
enum:
- running
- idle
mentionCheckStatus:
type: string
enum:
- running
- idle
relationshipSweepStatus:
type: string
enum:
- running
- idle
mentionCheckProgress:
type: object
properties:
done:
type: number
total:
type: number
additionalProperties: true
nullable: true
additionalProperties: true
````