---
title: "Add signals to a list"
method: POST
path: "/contacts/signals"
tags: ["contacts"]
---

# Add signals to a list

`POST /contacts/signals`

## Request

- Base URL: `https://api.bereach.ai`
- URL: `https://api.bereach.ai/contacts/signals`
- Auth: HTTP bearer

Starts, in the background, a run that gives each person on a list a dated reason to write to them now: a new role, their own recent posts, dated news about their company. Answers at once with the most the run costs; call again with start false for its progress.

## Request body

- object
  - `campaignId` string, required: The list to read.
  - `start` boolean: false reads where the last run stands and what a new one costs at most, without starting one.

## Response `200`

Whether a run started, the last run, and the quote

- object
  - `started` boolean, required
  - `running` boolean, required
  - `progress` object, nullable, required: The run this call started, else the last run, or null when the list never had one.
    - `state` 'running' | 'done' | 'stopped' | 'failed', required
    - `total` integer, required
    - `peopleRead` integer, required
    - `companies` integer, required
    - `companiesRead` integer, required
    - `found` integer, required: People who got a reason.
    - `credits` number, required
    - `startedAt` string, required
    - `endedAt` string
  - `people` integer, required: People a run reads.
  - `companies` integer, required: Their distinct companies, one news search each.
  - `credits` number, required: The most a run costs, in credits.
  - `run` object, nullable, required
    - `id` string, required
    - `kind` 'reasons' | 'fit', required
    - `state` 'running' | 'done' | 'stopped' | 'failed', required
    - `stoppedReason` 'user' | 'credits' | 'vendor' | 'lost'
    - `total` integer, required
    - `done` integer, required
    - `found` integer, required
    - `none` integer, required
    - `failed` integer, required
    - `skipped` integer, required
    - `credits` number, required
    - `creditsMax` number, required
    - `startedAt` string, required
    - `endedAt` string
    - `announcedAt` string
    - `stopRequestedAt` string
    - `contactIds` string[]
    - `extra` object
  - `quote` object, required
    - `kind` 'reasons' | 'fit', required
    - `people` integer, required
    - `alreadyDone` integer, required
    - `credits` number, required
    - `creditsLeft` number, nullable, required
    - `confirm` boolean, required
    - `affordable` boolean, required
    - `affordablePeople` integer, required
    - `extra` object
  - `refused` 'credits'
  - `stopping` boolean
  - `list_url` string: The list in the app, to give the user.

## Other responses

- `400`: The server cannot or will not process the request due to something that is perceived to be a client error.
- `401`: Although HTTP specifies "unauthorized", this response means "unauthenticated". Authenticate to continue. NOTE: 401 is also returned with code "linkedin_not_connected" on an endpoint that acts from your account (invitations, messages, your own network or inbox) when the caller IS authenticated but has no connected LinkedIn account: connect LinkedIn (not re-authenticate) to continue. Every other read never returns it.
- `403`: The caller is authenticated but not allowed. Read error.code: subscription_required (API key or connector whose plan is not active), free_draft_limit (a free-plan limit was reached), sales_nav_seat_inactive (no active Sales Navigator seat), or forbidden (not permitted).
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `410`: The requested content has been permanently deleted from the server.
- `422`: The request was well-formed but was unable to be followed due to semantic errors.
- `429`: Rate limit exceeded. Read error.retryAfter for the wait time in seconds.
- `500`: The server encountered a situation it does not know how to handle.
- `502`: An upstream service returned an error. Retry after a few seconds.
- `503`: Capacity is temporarily exceeded. Retry after a few seconds.

## Changes

> 39 revisions in range; 1 not diffed.

- **2026-10-22** `549f4adbbfcf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/berea/apis/bereach-api/changes/contacts/signals/post.md)

---

[API](https://skmtc.dev/berea/apis/bereach-api.md) · [All operations](https://skmtc.dev/berea/apis/bereach-api/llms.txt) · [OpenAPI document](https://skmtc.dev/berea/apis/bereach-api/revisions/b657f915ce03?raw)