---
title: "Quote and confirm the matching of a watchlist's companies"
method: POST
path: "/api/v1/watchlists/{signalId}/companies/confirm-matching"
tags: ["Watchlists"]
---

# Quote and confirm the matching of a watchlist's companies

`POST /api/v1/watchlists/{signalId}/companies/confirm-matching`

## Request

- Base URL: `https://api.rodz.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.rodz.io/api/v1/watchlists/{signalId}/companies/confirm-matching`
- Auth: HTTP bearer

See what it costs to start watching a large company list, and say yes — for a New Decision Maker or Account watchlist whose list you sent through the API or synced from HubSpot.

Before a company can be watched for new decision makers it is matched to its LinkedIn company page, and each match is billed. A small list is matched straight away; above a set amount nothing is matched or charged until you confirm, and the signal's `warnings` carry `MATCHING_CONFIRMATION_REQUIRED` with the quote. You are also told without asking: the account owners get an email with the quote and a link to confirm in the dashboard, and the signal's `webhookUrl` receives a `signal.action_required` event.

**Input:** `signalId` (path) and `confirm`: `false` (default) returns the quote only, `true` accepts it and starts the matching.

**Output:** `status` (`awaiting_confirmation`, `confirmed`, `insufficient_credits` or `nothing_to_match`), `companiesToMatch`, `alreadyMatchedFree` (companies matched before, free), `billableCompanies`, `pricePerCompany`, `currency`, `estimatedCost` (an upper bound — a company is charged only once it is matched), `sufficientBalance` and `confirmationRequired`.

Send the LinkedIn company URL of each company when you have it: it is matched exactly, and a numeric company URL (`/company/1234567`) is already matched and never billed.

## Path parameters

- `signalId` string, required: Id of the watchlist signal, as returned by the create endpoint.

## Request body

- object
  - `confirm` boolean: `true` confirms the cost quoted for matching this watchlist's companies and starts the matching. `false` (default) only returns the quote.

## Response `200`

Successful Response

- object: What matching this watchlist's companies costs, and whether it may start.
  - `status` 'nothing_to_match' | 'awaiting_confirmation' | 'insufficient_credits' | 'confirmed', required: `confirmed`: matching runs (or needs no confirmation). `awaiting_confirmation`: nothing is matched or charged until you call this endpoint with `confirm: true`. `insufficient_credits`: your balance does not cover `estimatedCost`; top up, then confirm. `nothing_to_match`: every company is already matched.
  - `companiesToMatch` integer, required: Companies not yet matched.
  - `alreadyMatchedFree` integer, required: Of those, companies we have already matched before: free.
  - `billableCompanies` integer, required
  - `pricePerCompany` number, required
  - `currency` 'credits' | 'eur', required: The unit of `pricePerCompany` and `estimatedCost`.
  - `estimatedCost` number, required: At most this much is charged: a company is charged only once it is matched.
  - `isUpperBound` boolean
  - `sufficientBalance` boolean, required
  - `confirmationRequired` boolean, required: True when the cost is above the amount we match without asking.

## Other responses

- `400`: The signal exists but watches the other kind of subject
- `404`: No watchlist signal with this id on your account
- `422`: Validation Error
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` response header.

---

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