> ## 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.

# Bulk people actions

> Preview or run email lookups for many outreach people at once.

The enrich action takes a `selection` and works through it in batches:

* `selection` is either `{ mode: "ids", ids: [personId, ...] }` or `{ mode: "all", filters: { search?, stage?, groups? }, excludedIds: [...] }` (every person matching the filters, minus the excluded ids).
* `scope` (`best` or `everyone`) applies to a select-all: `best` is one person per site, `everyone` is every matching person.
* Call `POST /v3/outreach/prospects/people/bulk-preview` with the `selection` and `action: "enrich"` first. It changes nothing and returns `eligibility`: `{ selected, eligible, skipped, byReason }`.

| Action | Endpoint | Rows per call | Notes |
| - | - | - | - |
| Enrich | `POST /v3/outreach/prospects/people/bulk-enrich` | 10 | 10 AI credits per eligible person queued; `402` when the charge fails. |

People already looked up, mid-lookup or marked `no_email` are skipped without a charge. Each call returns `{ 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 person with `id`, `success`, `creditsCharged` and `error` when the lookup could not be started. Lookups that finish without an address are refunded later, so `creditsCharged` is not necessarily the final cost.

Lookups run in the background. Poll [List every person](https://snowseo.com/docs/api-reference/endpoints/outreach-contacts-all-people.md) while queued people have `status` `enriching`; their rows report the eventual address or failure.

`POST /v3/outreach/prospects/people/selection` returns the people a `selection` matches. Get person IDs from [Outreach Contacts](https://snowseo.com/docs/api-reference/endpoints/outreach-contacts.md#list-a-prospects-people).


## OpenAPI

````yaml POST /v3/outreach/prospects/people/bulk-preview
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:
  - bearerAuth: []
  - apiKey: []
externalDocs:
  url: https://snowseo.com/docs
  description: Find more info here
paths:
  /v3/outreach/prospects/people/bulk-preview:
    post:
      tags:
        - Outreach
      summary: Count which selected people a bulk action applies to
      description: >-
        Read-only. For a selection of people (explicit ids, or all matching
        filters minus exclusions), reports how many the given bulk action would
        act on and why the rest would be skipped. Call it before a bulk action
        and confirm the counts with the user.
      operationId: outreachPeopleBulkPreview
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - selection
                - action
              properties:
                teamId:
                  type: string
                selection:
                  oneOf:
                    - type: object
                      required:
                        - mode
                        - ids
                      additionalProperties: false
                      properties:
                        mode:
                          type: string
                          enum:
                            - ids
                        ids:
                          type: array
                          items:
                            type: string
                    - type: object
                      required:
                        - mode
                        - filters
                        - excludedIds
                      additionalProperties: false
                      properties:
                        mode:
                          type: string
                          enum:
                            - all
                        filters:
                          type: object
                          properties:
                            search:
                              type: string
                            stage:
                              type: string
                              enum:
                                - all
                                - needs-email
                                - ready
                                - emailed
                            groups:
                              type: object
                              additionalProperties:
                                type: array
                                items:
                                  type: string
                        excludedIds:
                          type: array
                          items:
                            type: string
                action:
                  type: string
                  enum:
                    - enrich
                  description: The bulk action to count eligible rows for.
                scope:
                  type: string
                  enum:
                    - best
                    - everyone
                  description: >-
                    For a select-all: `best` is one person per site (the pick),
                    `everyone` is every matching person.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  eligibility:
                    type: object
                    required:
                      - selected
                      - eligible
                      - skipped
                      - byReason
                    properties:
                      selected:
                        type: number
                      eligible:
                        type: number
                      skipped:
                        type: number
                      byReason:
                        type: object
                        additionalProperties:
                          type: number
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
                  reference:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your SnowSEO API key (sk_...).
    apiKey:
      type: apiKey
      name: x-api-key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.