# Capabilities and endpoints (/docs/concepts/capabilities-and-endpoints)



The catalog describes every vendor API in the same shape. Browse it at [/providers](/providers)
and [/capabilities](/capabilities), or read it from the public
[catalog API](/docs/api/catalog/catalog_search).

## Capability [#capability]

A capability is a task with a fixed contract, whichever vendor performs it. `people.email.find`,
for example:

| Part          | Value                                                             |
| ------------- | ----------------------------------------------------------------- |
| Inputs        | `first_name`, `last_name`, `domain` (all required)                |
| Output fields | `email`, `confidence` (0–100)                                     |
| Hit           | A deliverable or accept-all email address is returned             |
| Accuracy      | Share of returned addresses that do not hard-bounce within 7 days |

The **hit** definition is what makes vendors comparable: routing stops on it, per-success pricing
charges on it, and quality scores count it.

Capabilities today include `people.email.find`, `email.verify`, `people.enrich`,
`people.profile.find`, `people.role.find`, `people.search`, `phone.mobile.find`,
`company.enrich` and `signals.job_change`.

## Endpoint [#endpoint]

An endpoint is one vendor's implementation, named `<vendor>/<endpoint>`:
`hunter/email.find`. It declares:

* its **input** schema (Hunter's is `first_name`, `last_name` and `domain`),
* how the vendor's response maps to the capability's output fields, and what counts as a hit,
* its **pricing model** and list price,
* which **credentials** it accepts: `byok` (your key), `managed` (GridRouter's account) or both,
* how the vendor bills your own key, for [billing verification](/docs/concepts/billing-verification).

`GET /v1/catalog/endpoints/{provider}/{endpoint}` returns all of it, including the input as JSON
Schema, the current quote and quality.

## Pricing models [#pricing-models]

| Model         | Charged                                                      |
| ------------- | ------------------------------------------------------------ |
| `per_call`    | Whenever the vendor answers, hit or not                      |
| `per_success` | Only on a hit (a miss can carry its own, usually zero, rate) |
| `per_result`  | Per returned record                                          |
| `per_unit`    | Per unit of input or output (rows, domains, credits, pages)  |
| `per_token`   | Per million tokens, read from the response                   |
| `async_task`  | A submit fee plus a completion fee charged only on success   |

Prices are integer micro-USD. `POST /v1/quote/{provider}/{endpoint}` returns the quote for a given
input without calling the vendor. On your own vendor keys GridRouter charges nothing, whatever the
model.

## Quality [#quality]

Every endpoint's quality comes from real traffic: reliability, coverage (fill), accuracy,
freshness, speed (p50 and p95 latency) and value (cost per verified hit). Rates are Wilson lower
bounds, so a small sample cannot rank high. The composite weighs accuracy 0.30, coverage 0.25,
reliability 0.20, freshness 0.10, speed 0.10 and reviews 0.05, and needs at least 200 calls; below
that, pages show "insufficient data". Use it with `sort: "quality"` when
[routing](/docs/concepts/routing).