> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich a list's people

> Enriches the people on one of your people lists in a job: finds the work email, phone number or both that each row lacks, and saves what was found on the rows. `find` and `providers` work as on `POST /v1/people/enrich`.

A run takes up to `maxRows` rows (10,000 at most, and when it is left out) from `offset` (0 when left out) in the list's order. Enrich a longer list in runs, each with `offset` where the last one ended: 0, then 10,000, then 20,000.

The answer is the job, with `202`. Follow it with `GET /v1/jobs/{jobId}`, then read what was found with `GET /v1/lists/{listId}/rows`. A list with nothing to enrich answers a job that has already ended, at no cost. Another organization's list answers `404` `list_not_found`, and a company list `422` `people_list_required`. Stop a running job with `POST /v1/jobs/{jobId}/cancel`.

To cap what the job may cost, send `maxSpendUsd`, in US dollars. A job that could cost more, going by what it would hold, answers `422` `max_spend_exceeded` with the amount it could cost, and nothing is held or started.

**Price:** per value found, by who found it: an email \$0.02 from the package or \$0.05 from the waterfall, a phone number \$0.05 from the package or \$0.10 from the waterfall. With `providers` `package`, every value costs the package price. Values a person already had are free. When the job starts, the most it can cost is held from your balance: for each row, \$0.02 to find an email, \$0.05 a phone number or \$0.07 both with the package, or \$0.05, \$0.10 and \$0.15 with the waterfall. When it ends it is charged for what it found, and the rest is released. Starts have their own limit, 10 a minute and 200 a day. **Scope:** enrichment, with a key that can write.



## OpenAPI

````yaml /openapi.json post /v1/lists/{listId}/enrich
openapi: 3.1.0
info:
  title: outbound.dev API
  version: v1
  description: Find people and companies, and see what every call costs, with one API key.
servers:
  - url: https://api.outbound.dev
security: []
tags:
  - name: People
    description: >-
      Search people with filters, a saved search or a plain-language query,
      count matches and look up filter values.
  - name: Companies
    description: >-
      Search companies, count matches, name one company by its name, domain or
      LinkedIn page, and list its people.
  - name: Saved searches
    description: Keep a search under a title and run it again, for people or for companies.
  - name: Lists
    description: >-
      Keep people or companies in lists: create and change lists, page through
      their rows, and add or remove people.
  - name: Folders
    description: Group lists of one kind into folders.
  - name: Enrichment
    description: >-
      Find people's work emails and phone numbers: one person, a batch of
      people, or a list.
  - name: Jobs
    description: >-
      Long tasks a call started: their progress, what they produced and what
      they were charged, and stopping them.
  - name: Accounts
    description: >-
      Connect the mailboxes and LinkedIn seats that campaigns and the inbox send
      from, and look after them.
  - name: Campaigns
    description: >-
      Email and LinkedIn campaigns: their steps, the people they enroll, their
      queue of messages, templates, the knowledge hubs and writing styles AI
      steps are written from, the tracking domain their links go through, and
      the lists every campaign leaves out.
  - name: Inbox
    description: >-
      Read and answer the conversations of your mailboxes and LinkedIn seats,
      and send new messages and invitations.
  - name: Account
    description: >-
      The calling key and its organization, its rate limits, and revoking the
      key.
  - name: Billing
    description: The balance, the ledger of every change to it, and the price list.
  - name: Usage and requests
    description: >-
      Calls and spend by day, and the record of every request of the last 30
      days.
paths:
  /v1/lists/{listId}/enrich:
    post:
      tags:
        - Enrichment
      summary: Enrich a list's people
      description: >-
        Enriches the people on one of your people lists in a job: finds the work
        email, phone number or both that each row lacks, and saves what was
        found on the rows. `find` and `providers` work as on `POST
        /v1/people/enrich`.


        A run takes up to `maxRows` rows (10,000 at most, and when it is left
        out) from `offset` (0 when left out) in the list's order. Enrich a
        longer list in runs, each with `offset` where the last one ended: 0,
        then 10,000, then 20,000.


        The answer is the job, with `202`. Follow it with `GET
        /v1/jobs/{jobId}`, then read what was found with `GET
        /v1/lists/{listId}/rows`. A list with nothing to enrich answers a job
        that has already ended, at no cost. Another organization's list answers
        `404` `list_not_found`, and a company list `422` `people_list_required`.
        Stop a running job with `POST /v1/jobs/{jobId}/cancel`.


        To cap what the job may cost, send `maxSpendUsd`, in US dollars. A job
        that could cost more, going by what it would hold, answers `422`
        `max_spend_exceeded` with the amount it could cost, and nothing is held
        or started.


        **Price:** per value found, by who found it: an email \$0.02 from the
        package or \$0.05 from the waterfall, a phone number \$0.05 from the
        package or \$0.10 from the waterfall. With `providers` `package`, every
        value costs the package price. Values a person already had are free.
        When the job starts, the most it can cost is held from your balance: for
        each row, \$0.02 to find an email, \$0.05 a phone number or \$0.07 both
        with the package, or \$0.05, \$0.10 and \$0.15 with the waterfall. When
        it ends it is charged for what it found, and the rest is released.
        Starts have their own limit, 10 a minute and 200 a day. **Scope:**
        enrichment, with a key that can write.
      operationId: postListsListIdEnrich
      parameters:
        - name: listId
          in: path
          required: true
          description: The people list whose rows to enrich.
          schema:
            type: string
            minLength: 24
            maxLength: 24
            pattern: ^[0-9a-fA-F]+$
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Names this operation, so a retry with the same key and body gets the
            first success again, marked `Idempotent-Replayed`, instead of
            running or charging twice. A mailbox's `password` is not compared:
            the same mailbox sent again with another password is the same call,
            and gets the first answer. Kept 24 hours for your organization and
            this route. A refusal (`4xx`) frees the key at once, so a corrected
            retry runs. After a server error (`5xx`), which may still take
            effect, the key stays held for 5 minutes from the call's start, and
            a retry in that time answers `409` `idempotency_in_progress`; after
            that, a send or import that may already have gone out answers `409`
            `idempotency_outcome_unknown` instead of running again. 1 to 255
            visible ASCII characters, such as a UUID.
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[\x21-\x7E]+$
          example: 5f1c9d2e-8a4b-4e7c-9f30-6b2a1d8e4c75
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                find:
                  type: string
                  description: >-
                    What to find: a work `email` (the default), a `phone`
                    number, or both (`email_and_phone`).
                  enum:
                    - email
                    - phone
                    - email_and_phone
                  default: email
                providers:
                  type: string
                  description: >-
                    Where to look: `package` (the default) searches our own data
                    package; `waterfall` searches the package, then a fixed
                    series of further providers. A value's price depends on who
                    found it.
                  enum:
                    - package
                    - waterfall
                  default: package
                maxRows:
                  type: integer
                  description: >-
                    The most rows to enrich, from 1 to 10,000. Left out, the job
                    runs over every row up to that many.
                  minimum: 1
                  maximum: 10000
                offset:
                  type: integer
                  description: >-
                    How many of the list's rows, in its order, to skip before
                    the run starts: 0 when left out. Enrich a long list in runs,
                    each with `offset` where the last one ended.
                  minimum: 0
                maxSpendUsd:
                  type: number
                  description: >-
                    The most the job may cost, in US dollars. A job that could
                    cost more is refused before anything is held or started.
                  minimum: 0.01
                  maximum: 1000000
            example:
              find: email_and_phone
              providers: package
              maxRows: 500
              offset: 0
              maxSpendUsd: 35
      responses:
        '202':
          description: >-
            The job, started. Read its progress and result with `GET
            /v1/jobs/{jobId}`. A list with nothing to enrich answers a job that
            already ended, at no cost.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-Charged-Usd:
              $ref: '#/components/headers/ChargedUsd'
            X-Balance-Usd:
              $ref: '#/components/headers/BalanceUsd'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - type
                  - status
                  - units
                  - createdAt
                properties:
                  id:
                    type: string
                  type:
                    type: string
                    enum:
                      - email_verification
                      - people_enrichment
                      - list_enrichment
                    description: What the job does.
                  status:
                    type: string
                    enum:
                      - running
                      - succeeded
                      - failed
                      - cancelled
                    description: >-
                      `running` until the job ends as `succeeded`, `failed` or
                      `cancelled`.
                  listId:
                    type: string
                    description: >-
                      For a list enrichment, the list it runs over. What it
                      finds is saved on the list's rows: read them with `GET
                      /v1/lists/{listId}/rows`.
                  find:
                    type: string
                    enum:
                      - email
                      - phone
                      - email_and_phone
                    description: For an enrichment, what it looks for.
                  providers:
                    type: string
                    enum:
                      - package
                      - waterfall
                    description: For an enrichment, where it looks.
                  progress:
                    type: object
                    description: How far the job got. Absent until it reports progress.
                    properties:
                      done:
                        type: integer
                      total:
                        type: integer
                  units:
                    type: array
                    description: What the job produced so far, by price item.
                    items:
                      type: object
                      properties:
                        item:
                          type: string
                        units:
                          type: integer
                  chargedUsd:
                    type: string
                    description: >-
                      What the job was charged, in US dollars as an exact
                      six-decimal string. Present once it ended.
                  results:
                    type: array
                    description: >-
                      For a people enrichment, once it ended: every person's
                      result, in the order the request named them. Shown to keys
                      that can read enrichment.
                    items:
                      type: object
                      description: >-
                        The person as `POST /v1/people/enrich` answers them,
                        with their place in the request, or, when they were not
                        enriched, their place and why. Nothing is charged for a
                        person with an `error`.
                      required:
                        - index
                      properties:
                        index:
                          type: integer
                          description: >-
                            The person's place in the request's `people`, from
                            0.
                        personId:
                          type: string
                          description: >-
                            The person's id in your workspace, as list rows and
                            `personIds` name it. Send it as `personId` to enrich
                            them again. Absent when the person could not be
                            saved.
                        emails:
                          type: array
                          description: >-
                            Every work email address the person has whose check
                            showed it can receive mail: `valid`, or `catch-all`
                            (the domain accepts mail for any address, so this
                            one could not be confirmed). Personal addresses are
                            left out.
                          items:
                            type: object
                            required:
                              - email
                              - status
                            properties:
                              email:
                                type: string
                              status:
                                type: string
                                enum:
                                  - valid
                                  - catch-all
                        phones:
                          type: array
                          description: >-
                            Every phone number the person has, with what
                            checking it showed.
                          items:
                            type: object
                            required:
                              - phoneNumber
                            properties:
                              phoneNumber:
                                type: string
                              status:
                                type: string
                                enum:
                                  - valid
                                  - hq
                                  - unverified
                                description: '`hq` is the company''s main line.'
                        primaryEmail:
                          type: string
                          description: >-
                            The address to write to. Absent when the person has
                            no address in `emails`.
                        primaryPhone:
                          type: string
                          description: >-
                            The number to call. Absent when the person has no
                            phone number.
                        found:
                          type: object
                          description: >-
                            What this call found that the person did not have:
                            the values it was charged for. Empty when it found
                            nothing new.
                          properties:
                            email:
                              type: object
                              description: >-
                                The work email address found. Absent when none
                                was.
                              required:
                                - email
                                - foundBy
                              properties:
                                email:
                                  type: string
                                foundBy:
                                  type: string
                                  enum:
                                    - package
                                    - waterfall
                                  description: >-
                                    Who found the value, which sets its price:
                                    `package` or `waterfall`.
                            phone:
                              type: object
                              description: The phone number found. Absent when none was.
                              required:
                                - phoneNumber
                                - foundBy
                              properties:
                                phoneNumber:
                                  type: string
                                foundBy:
                                  type: string
                                  enum:
                                    - package
                                    - waterfall
                                  description: >-
                                    Who found the value, which sets its price:
                                    `package` or `waterfall`.
                        error:
                          type: object
                          description: >-
                            Why the person was not enriched: `person_not_found`,
                            `person_not_identifiable`, `enrichment_in_progress`
                            (another call was enriching them),
                            `enrichment_failed`, or `enrichment_not_run` (the
                            job ended before it reached them). Absent when they
                            were enriched.
                          required:
                            - code
                            - message
                          properties:
                            code:
                              type: string
                              enum:
                                - person_not_found
                                - person_not_identifiable
                                - enrichment_in_progress
                                - enrichment_failed
                                - enrichment_not_run
                            message:
                              type: string
                  createdAt:
                    type: string
                    format: date-time
                  finishedAt:
                    type: string
                    format: date-time
                    description: When the job ended. Absent while it runs.
              example:
                id: 6a1f0c2b9d4e8a7f3c5b2e14
                type: list_enrichment
                status: running
                listId: 6a1f0c2b9d4e8a7f3c5b2e20
                find: email_and_phone
                providers: package
                units: []
                createdAt: '2026-11-15T10:00:00.000Z'
        '429':
          $ref: '#/components/responses/RateLimited'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
components:
  headers:
    RequestId:
      description: The request's id. Quote it when you write to support.
      schema:
        type: string
        example: req_6a1f0c2b9d4e8a7f3c5b2e10
    ChargedUsd:
      description: What this call cost, in US dollars as an exact six-decimal string.
      schema:
        type: string
        example: '0.005000'
    BalanceUsd:
      description: >-
        The organization's balance after this call, in US dollars as an exact
        six-decimal string.
      schema:
        type: string
        example: '9.995000'
    RateLimitLimit:
      description: >-
        The calls allowed in the window of the route's limit with the fewest
        calls left.
      schema:
        type: integer
        example: 20
    RateLimitRemaining:
      description: The calls left in that window.
      schema:
        type: integer
        example: 19
    RateLimitReset:
      description: Seconds until that window resets.
      schema:
        type: integer
        example: 42
    IdempotentReplayed:
      description: >-
        `true` on an answer given again for an `Idempotency-Key`: it is the
        first call's, and nothing ran or was charged this time. Absent
        otherwise.
      schema:
        type: string
        enum:
          - 'true'
    RetryAfter:
      description: Seconds to wait before calling again.
      schema:
        type: integer
        example: 42
  responses:
    RateLimited:
      description: >-
        Too many calls. Wait the seconds in Retry-After, then call again. When
        the limit reached does not say when it resets, such as a mail provider's
        own limit on a mailbox, Retry-After is 60. The RateLimit headers
        describe this API's own limits, so they come only with a 429 one of
        those gave. The body is empty.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
    Error:
      description: The request was refused. The body names the reason in `error.code`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        Something failed on our side and nothing was charged. Retry with
        backoff; quote X-Request-Id if it persists. The body is empty.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - doc_url
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable: branch on it. It never changes
                meaning.
            message:
              type: string
              description: >-
                A human-readable explanation for logs. It may be reworded at any
                time.
            param:
              type: string
              description: The request field the error is about, when there is one.
            doc_url:
              type: string
              description: The code's entry in the errors reference.
            request_id:
              type: string
              description: >-
                The request's id, as in the X-Request-Id header. Quote it to
                support.
      example:
        error:
          code: insufficient_balance
          message: Your balance cannot cover this call. Add funds and try again.
          doc_url: https://docs.outbound.dev/errors#insufficient_balance
          request_id: req_6a1f0c2b9d4e8a7f3c5b2e10
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key from the console, starting `ob_live_`, sent as
        `Authorization: Bearer <key>`.

````

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