# Provider playbook

Vendor examples help map the workflow to your own tools. Consult the provider's current catalog, credentials, region coverage, billing unit, and price before a paid call. A per-result price is not comparable to a per-search price without knowing the expected result count. No historic price is a current quote.

Possible routes include natural-language people search, structured company-and-role search, routed work-email discovery, and a separate deliverability verifier. Choose the providers you already have authorization to use. Keep credentials in your secure connection flow.

## Request shapes

`/call/<endpoint-id>` forwards the upstream method, query, and body. Set the route ceiling and use a credential injected by your runtime. The value below is a placeholder, not a real credential.

```bash
curl -sS 'https://treg.to/call/treg.people.email.find' \
  -H 'X-Treg-Token: <credential-from-secret-store>' \
  -H 'X-Treg-Route-Max-Cost: 0.05' \
  -H 'Content-Type: application/json' \
  --data '{"full_name":"<person-name>","domain":"<company-domain>"}'
```

The routed finder also accepts `linkedin_url` instead of name and domain. To verify an address, consult `https://treg.to/use-cases/verify-an-email.md` for the current provider's method and parameter schema before calling `leadmagic.people.email.verify`. Don't guess its request body.

The Tomba phone endpoint uses GET, not POST. Only call it for a shortlist where phone use is appropriate.

```bash
curl -sS --get 'https://treg.to/call/tomba.people.phone.find' \
  --data-urlencode 'linkedin=<public-profile-url>' \
  -H 'X-Treg-Token: <credential-from-secret-store>' \
  -H 'X-Treg-Route-Max-Cost: 0.05'
```

`hunter.x.combined-find` takes `email` as a query parameter; sending that field in a JSON body can fail. Some upstream responses contain `output` and `_treg` with `served_by`, `outcome`, `charged_micro`, and `tried`; others return the upstream object directly. Handle both shapes.

## Billing and error handling

- 402: prepaid balance is exhausted. Stop, report the balance error, and wait for funding or switch to an already-authorized provider.
- 503 with `provider_capacity_unavailable`: that provider is unavailable. Try an alternate provider; don't assume your request was charged.
- 503 with `treg_saturated: true` and `Retry-After`: retry after the instructed delay.
- 429, 5xx, timeout: respect retry guidance and provider limits. Check receipts before attempting a potentially billed retry.
- 4xx parameter error or missing required price: fix the request or authorization before trying again.
- When retrying after a lost response, reuse the same `Idempotency-Key` to avoid paying twice. Give new work a new key.

Catalog pages for [people search](https://treg.to/use-cases/people-search.md), [work email finding](https://treg.to/use-cases/find-professional-emails.md), and [verification](https://treg.to/use-cases/verify-an-email.md) include provider-specific schemas. In Sauna, its connection proxy can inject the token; elsewhere use a secure credential store and the provider's documented authentication.