# Company signals

> Watch the companies you sell to and see when one posts new roles, raises a round, makes the news or changes its leadership, each with a link to the source, checked once a day inside a budget you set.

Source: https://docs.ayinbox.com/guides/signals/

A signal is a dated reason to write to a company now: it is hiring, it raised money, it was in the news, or someone new runs a team there. AY Inbox checks the companies your workspace watches once a day through [Looot](https://looot.ai/), keeps what is new, and links every signal to the page that shows it happened.

Signals run on the instance's Looot balance, so the operator has to turn them on first (`AYINBOX_LOOOT_SIGNALS`, see [configuration](/development/configuration/)). On an instance that bills with credits, the workspace pays for each lookup in [credits](/guides/ai-credits/).

The four kinds of signal [#the-four-kinds-of-signal]

| Signal         | Where it comes from                                | What a check keeps                                                                                          |
| -------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Hiring**     | The company's job openings (`jobs.company`)        | Roles first seen in the last 30 days, each linked to its job page                                           |
| **Funding**    | The company's financing events (`company.funding`) | Rounds first seen in the last 90 days, with the round type and amount, linked to the announcement           |
| **News**       | News about the company (`company.news`)            | Articles that name the company, linked to the article                                                       |
| **Leadership** | The same news lookup                               | Hires, promotions and departures of senior people (a chief, a VP, a head of a team, a founder or the board) |

Anything older than 90 days is left out, and a check keeps at most 10 signals per lookup. Hiring and funding lookups are pinned to a provider that answers for the domain it was asked about, and a row in their answer that names a different company is dropped.

How news is matched [#how-news-is-matched]

A news provider can ignore the domain it was sent and return unrelated articles while still reporting a hit. AY Inbox never sends news lookups to the provider seen doing this, and it keeps an article only when it is about the company:

* the article names the company's domain, or comes from a page on that domain, or
* it names the company as a whole word (legal suffixes such as "Inc." are dropped, and a name of two letters or fewer is not used), or
* the provider files it as an event of that company.

An article that does none of these is dropped. The lookup that returned it is still paid for.

A news item becomes a **leadership** signal when the provider files it as a hire, promotion, departure or retirement, or when its headline says someone was appointed, named, hired, promoted or stepped down as a senior role. A headline that says the company raised, secured or closed a round becomes a **funding** signal. Everything else stays **news**.

Looot's catalog has no feed of job changes per company yet, so leadership changes are read from news rather than from a people database.

The same signal is never shown twice [#the-same-signal-is-never-shown-twice]

A signal is identified by its kind, the company and its evidence link with the tracking parameters removed (`utm_*`, `fbclid`, `gclid` and the like, and the whole query of a LinkedIn job page). Finding the same page again on another day, or through another lookup, adds nothing.

Watch companies [#watch-companies]

Open **Contacts**, then **Signals**, then **Watched companies**. Add companies in any of three ways:

* **By domain.** Paste domains, websites or addresses: `https://www.acme.io/about` and `ana@acme.io` both become `acme.io`. Free-mail hosts such as `gmail.com` are refused, because they are not a company.
* **From contacts.** Adds the 50 company domains most of your contacts are at, skipping free-mail hosts and domains already watched, with the most common company name your contacts give for each.
* **From a segment.** The same, over the members of a [segment](/guides/segments/).

A workspace watches up to 500 companies. Each row shows when the company was last checked, how many signals it has, and why a check stopped if one did. Pause a company to skip it in the daily check, or remove it. Removing a company keeps the signals already found.

The daily check [#the-daily-check]

Once a UTC day, AY Inbox checks every watched company that is not paused: one hiring, one funding and one news lookup. Each lookup is capped at $0.015, so a company costs at most $0.045 a day, and usually less. A lookup costs what Looot bills for it, whether or not it yields a signal: a miss is free only when the provider does not bill misses.

* **A daily budget.** Each workspace has one, $1 by default (the operator can change the default with `AYINBOX_LOOOT_SIGNALS_DAILY_USD`). Change it under **Signals > Budget**, from $0 to $50 a day. A lookup only starts when its cap fits in what is left of the day's budget; companies that do not fit wait for the next day, marked **Waiting for budget**, unless you raise the budget, which lets the next hourly pass try them again. The budget resets at midnight UTC.
* **Choose the lookups.** Turn hiring, funding or news off under **Budget** to spend nothing on it.
* **Pause the daily check.** Turning **Daily checks** off stops the automatic check; **Check now** still works.
* **Never paid twice.** Every lookup has an idempotency key made from the workspace, the company, the lookup and the UTC day. Checking the same company again the same day reuses the first answer at no cost, and a check interrupted by a restart picks up where it stopped.
* **Costs Looot has not settled.** A lookup Looot has not answered yet is retried on the next hourly pass with the same key, which settles it without billing it again, and that carries on after the UTC day ends. Until then its cap counts against its day's budget. Looot is asked for up to 7 days; after that the lookup is closed. A lookup Looot answered without reporting a cost keeps its cap counted for its day until the cost arrives.

On a hosted workspace the daily check runs only while the workspace has a paid plan that includes integrations. Without one, you can still keep a watch list, each row says **Needs a paid plan**, and the check starts within a few hours of upgrading.

Check now [#check-now]

**Check now** on the **Watched companies** tab checks every watched company that is not paused, up to 25 at a time, within a budget you set ($0.05 to $50, $0.50 by default); the refresh button on a row checks only that company. It also stays inside the day's budget. A lookup that already finished today costs nothing, and one turned on since today's check is new spend, so it needs the budget and the credits like any other. New signals appear in the feed as they are found.

Where signals show [#where-signals-show]

* **The Signals feed** lists every signal, newest first, filtered by kind and age. Each row opens its evidence page in a new tab.
* **Contacts.** A contact at a company with a signal in the last 30 days carries a small badge next to their company, matched on the domain of their address.
* **Segments.** Filter contacts with **Last hiring signal**, **Last funding signal**, **Last news signal**, **Last leadership change** or **Last company signal**, for example "in the last 14 days". See [segments](/guides/segments/).
* **Webhooks.** `signal.detected` fires once for each new signal. See [webhook events](/api/reference/webhooks/).
* **Live.** Teammates see new signals arrive without refreshing.

Credits [#credits]

On an instance that bills with credits, each lookup is charged once Looot settles its cost: the settled spend divided by the operator's price per credit, rounded up. The default is one credit per $0.01, so a lookup that cost $0.01 is one credit. A lookup that yields no signal is charged what Looot billed for it, which is nothing only when the provider does not bill the miss.

* The charge is taken before the lookup's signals are stored, so signals your workspace could not pay for are not handed over. They are stored after you add credits, when the next pass replays the lookup at no extra Looot cost.
* A lookup only starts when the workspace has the credits for its cap. When they run out, the daily check tries again every hour and the rows say **Out of credits**.
* A lookup Looot answered without reporting a cost is charged its cap, two credits at the default price, and its signals are stored. When Looot reports the cost, the settled spend is charged and the cap is given back as **Looot company signals refund**. If it never reports one within 7 days, the cap stays charged.
* A lookup still running when the day ends is charged when it settles, even though the company has been checked again since.
* Charges appear in the transaction log under **Settings > Billing** as **Looot company signals**, naming the company and the lookup, and count toward your [spend limits](/guides/ai-credits/#usage-and-spend-controls). A manual check is attributed to the member who started it.

Use the API [#use-the-api]

```json
POST /v1/signals/companies
{ "domains": ["acme.io", "https://www.example.com"] }
```

The body can name `domains`, `companies` (each a `domain` and an optional `name`), `contact_ids`, `from_contacts: true` or a `segment_id`, with `limit` (1 to 100, 50 by default) for the last three. The answer lists the companies `added` and how many were `existing`.

```json
POST /v1/signals/check
{ "company_ids": ["2c1f..."], "max_cost_usd": 0.5 }
```

Leave `company_ids` out to check every watched company, up to 25. The answer is `202` with `queued`, `already_checked_today`, `estimated_max_usd` and what is left of the day's budget. Send an `Idempotency-Key` header with either `POST` so a retry returns the first answer.

* `GET /v1/signals` lists signals, newest first, with `types` (comma separated), `domain`, `days` (1 to 365), `limit` (1 to 200) and the opaque `cursor` from `pagination.next_cursor`.
* `GET /v1/signals/domains?days=30` summarizes recent signals per company domain.
* `GET /v1/signals/companies`, `PATCH` and `DELETE /v1/signals/companies/:companyId` read, rename or pause, and remove watched companies.
* `GET /v1/signals/settings` returns the settings, today's spend and each lookup's cap; `PUT /v1/signals/settings` takes `daily_budget_usd`, `paused` and `lookups`.

Who can do what [#who-can-do-what]

| Action                                     | Member permission                    | API key scope                       |
| ------------------------------------------ | ------------------------------------ | ----------------------------------- |
| See signals, the watch list and the budget | View contacts                        | `READ_CONTACTS`                     |
| Add, rename, pause and remove companies    | Manage contacts                      | `WRITE_CONTACTS`                    |
| Check now                                  | Use integrations and manage contacts | `INTEGRATIONS` and `WRITE_CONTACTS` |
| Change the daily budget and lookups        | Manage settings                      | `INTEGRATIONS`                      |

On a hosted workspace, **Check now** and changing the budget also need a paid plan that includes integrations. See the [endpoint scope map](/api/endpoints/) and the [error codes](/api/error-codes/).

Good to know [#good-to-know]

* The headline, detail and link of a signal come from outside providers. AY Inbox shows them as text and opens links in a new tab.
* Watched companies, their signals and the signal settings move with the contacts group in a [workspace export](/guides/workspace-export-import/). The record of what each lookup cost stays behind, and the destination checks each company again.
* Signals are kept for a year after they were first found, and the record of each lookup for 90 days. See [data control](/development/data-control/#company-signals).
* A signal is evidence that something happened, not a promise that a company is ready to buy. Read the source before you write.