> ## 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.
# Contacts
> Find who to pitch at a prospect's site, then resolve the email addresses of the people worth writing to.
Getting someone to write to is deliberately **two steps**: first find out who works at a site, then buy an address only for the people you actually want. That split is what stops you paying for forty addresses when one person was the right one.
Requests are scoped to the brand your API key belongs to. See [Authentication](/docs/api-reference/authentication).
***
## Find people
`POST /outreach/prospects/find-people`
[Open the request and response reference](/docs/api-reference/endpoints/outreach-find-people).
Looks up the people worth pitching at one site or a batch of them - editors, writers, whoever can actually add the link. Nothing is bought here: you get names, job titles and seniority so you can decide.
**Body**: `prospectIds`, up to 50. Optionally pass `terms`, 3-25 distinct job titles to match; omit it for the default editorial, SEO, marketing, and owner roles.
Runs in the background. The response has `enqueuedCount`, `enqueuedProspectIds`, `skipped`, and `creditsCharged`. Poll [Outreach Prospects](/docs/api-reference/endpoints/outreach-prospects) while each enqueued site's `status` is `finding_people`, then read the result with [List a prospect's people](#list-a-prospects-people).
**Costs 5 AI credits per site.** Sites whose search is already running are skipped and cost nothing, so a retry is safe. Do not re-run it on prospects that already have people.
`GET /outreach/prospects/people-search-terms` returns suggested title groups, defaults, and the allowed term count before a custom search.
***
## List a prospect's people
`GET /outreach/prospects/{id}/people`
Everyone found at one site.
| Field | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `fullName` | Their name |
| `title` | Job title - the thing worth deciding on |
| `seniority` | `Founder`, `C-Suite`, `Vice President`, `Director`, and so on |
| `companyName` | Where they actually work. Often **not** the site being pitched, since people search returns guest authors and contributors |
| `linkedinUrl` | Their profile, when there is one |
| `status` | `pending`, `enriching`, `enriched`, `no_email`, `failed` |
| `email` | The resolved address, or `null` if you have not bought one yet |
For a link on a blog post, a content editor or head of content answers far more reliably than a founder. Read `title`, not `seniority`.
## List every person
`GET /outreach/prospects/people`
The same rows across all prospects, with their site, role and resolved address, for export. Cap with `limit`; the response flags when the ceiling was hit.
***
## Resolve email addresses
Use [Find Outreach Email](/docs/api-reference/endpoints/outreach-find-email) for people at one prospect, or [Find Emails in Bulk](/docs/api-reference/endpoints/outreach-find-emails-bulk) for people across prospects. Both pages render the request and response schemas from OpenAPI.
**Costs 10 AI credits per person actually looked up.** Anyone already enriched or mid-lookup is dropped server-side and costs nothing, so a retry is safe. Anyone with no findable address is refunded automatically.
There is no product cap on how many people you enrich at once, only a request-size bound well above any real contact list. The cost is per person, so check the count before you send it.
***
## List a prospect's addresses
`GET /outreach/prospects/{id}/emails`
Every address found for one prospect, best first. **The `id` of a row here is the `prospectEmailId`** that [Queue pitches](/docs/api-reference/endpoints/outreach-sending#queue-pitches) and [Draft a pitch](/docs/api-reference/endpoints/outreach-sending#draft-a-pitch) take.
| Field | Description |
| ---------------- | ------------------------------------------------------- |
| `email` | The address |
| `name` / `role` | Who it belongs to |
| `verifiedStatus` | `valid`, `catchall`, `greylisted`, `unknown`, `invalid` |
| `confidence` | 0-100 |
| `sourceLayer` | How it was found |
| `isPrimary` | The address to use for the person it belongs to |
### What `verifiedStatus` means
| Value | Meaning | Safe to send? |
| ------------ | ----------------------------------------------------------------------- | ------------------------------ |
| `valid` | Their mail server confirmed the inbox exists | Yes |
| `catchall` | The server accepts mail to any address, so this exact inbox is unproven | Usually, expect the odd bounce |
| `greylisted` | The server asked us to check back later, so the check did not finish | Retry later |
| `unknown` | Their mail server could not be reached | Your call |
| `invalid` | The server rejected the address outright | **No** - it will bounce |
Sending to `invalid` addresses is the fastest way to damage a sending domain's reputation, and a held-back reputation affects every email you send afterwards. Filter them out before queueing.
***
## Choose a person's address
`PATCH /outreach/prospects/{id}/emails/{emailId}`
**Body**: `isPrimary: true`.
Picks which of one person's addresses to write to, so promoting one leaves the other people at the site untouched. Most people have a single address, where it is already set.
## Choose who to write to
`PATCH /outreach/prospects/{id}/people/{personId}`
**Body**: `isTarget` - `true`, `false` or `null`.
Marks one person as the site's outreach target and clears the flag on the others. `false` rules a person out, and `null` leaves it undecided, which is the default: with nobody chosen, the strongest address wins.
## OpenAPI
````yaml GET /v3/outreach/prospects/{id}/people
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/{id}/people:
get:
tags:
- Outreach
summary: List the people found at a prospect's site
description: >-
People discovered at one site, with their role and whether an address
has been resolved for them. Populated by outreach_find_people.
operationId: listOutreachProspectPeople
parameters:
- schema:
type: string
in: path
name: id
required: true
description: Prospect ID.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
people:
type: array
items:
type: object
properties:
id:
type: string
isNew:
type: boolean
createdAt:
type: string
updatedAt:
type: string
lastActivityAt:
type: string
description: >-
Latest update to this person or an address linked to
them. People are returned newest first by this time.
fullName:
type: string
title:
type: string
nullable: true
seniority:
type: string
nullable: true
companyName:
type: string
nullable: true
linkedinUrl:
type: string
nullable: true
location:
type: string
nullable: true
countryCode:
type: string
nullable: true
status:
type: string
lastError:
type: string
nullable: true
isTarget:
type: boolean
nullable: true
email:
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
nullable: true
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
additionalProperties: true
additionalProperties: true
````