# Credits in the API (https://webmetic.de/docs/en/api/credits)

Only two endpoints cost credits: `POST /contacts/reveal` and `POST /contacts/find`. For example, you use `/contacts/search` to look for the head of sales at a beverage maker that visited your pricing page. That search is free; only unlocking the email address costs credits.

You buy credits in the dashboard, not through the API. Where your credits come from and where you find the invoice is covered under [Credits](https://webmetic.de/docs/en/credits).

## From call to deduction [#from-call-to-deduction]

1. **Request the unlock**: You call `/contacts/reveal` or `/contacts/find` and choose email, phone, or both.
2. **Check credits**: Webmetic checks whether your credits cover every data type you requested. If they don't, the API answers with status `402`.
3. **Deliver data**: Webmetic looks up the contact details and delivers what it finds.
4. **Deduct credits**: Webmetic only deducts credits for the data types it delivered.

## Paid and free endpoints [#paid-and-free-endpoints]

These endpoints cost credits:

- **`POST /contacts/reveal`**: unlocks the email or phone of a person from your search. You choose the data type with `reveal_email` and `reveal_phone`.
- **`POST /contacts/find`**: finds a matching person and unlocks their details in the same call. You choose with `reveal` between `email`, `phone`, and `both`. Without a value, the call unlocks the email.

All other endpoints cost no credits: `/contacts/search`, `/contacts/lookup`, `/contacts/credits`, the Visitor Intelligence endpoints, and the webhooks. Enrichment currently costs no credits. For details, see [Enrichment](https://webmetic.de/docs/en/enrichment).

Requests with the [demo key](https://webmetic.de/docs/en/api/schnellstart#try-it-without-an-account) `wmtc_demo` never cost credits, not even on `/contacts/reveal` and `/contacts/find`.

Search and unlocking only work once your account has [set up contacts](https://webmetic.de/docs/en/ansprechpartner/einrichten). Until then, the API answers with `CONTACTS_SETUP_REQUIRED`.

The same rules apply in the AI assistant and in n8n, Make, and Zapier, because these connections use the same endpoints.

## Deduction rules [#deduction-rules]

Webmetic charges per data type, and email (with the LinkedIn profile when one exists) and phone are two separate types:

- **Delivered data only**: If Webmetic doesn't find a data type, that data type costs nothing, even when the search marked it as available.
- **No match**: If `/contacts/find` finds no matching person, the API answers with `found: false` and deducts nothing.
- **Opening again**: Data your account has already unlocked costs nothing again for every user and key of your account. The response then contains `from_cache: true`.
- **New data type**: If you later request the phone in addition to the email, you only pay for the phone.
- **Never twice**: Webmetic deducts repeated or simultaneous requests for the same data only once.
- **All or nothing**: If you request email and phone in one call, Webmetic deducts both together or not at all.
- **Errors**: If a call ends with an error, Webmetic deducts nothing.

Another Webmetic account pays for the same data itself. An unlock can't be undone, and the API doesn't return a history of the credits you used.

## Credits in responses [#credits-in-responses]

Every response from `/contacts/search`, `/contacts/reveal`, and `/contacts/find` contains two fields about your credits:

- **`credits_used`**: how many credits this call deducted.
- **`credits_remaining`**: how many credits your account has left after the call.

So you don't need a separate credits call after each action.

## Credits endpoint [#credits-endpoint]

`GET /contacts/credits` shows how many credits your account has and what each action costs. The call is free and also works before you set up contacts.

```bash tab="cURL" tab-group="lang"
curl "https://hub.webmetic.de/contacts/credits" \
  -H "Authorization: wmtc_YOUR_API_KEY"
```

```js tab="JavaScript" tab-group="lang"
const res = await fetch('https://hub.webmetic.de/contacts/credits', {
  headers: { Authorization: 'wmtc_YOUR_API_KEY' },
});
const credits = await res.json();
```

```python tab="Python" tab-group="lang"
import requests

res = requests.get(
    "https://hub.webmetic.de/contacts/credits",
    headers={"Authorization": "wmtc_YOUR_API_KEY"},
)
credits = res.json()
```

| Field | Type | Meaning |
| --- | --- | --- |
| `balance` | Integer | How many credits your account has. An account without credits gets `0`, not an error |
| `costs` | Object | Cost per action in credits |
| `costs.search` | Integer | Searching for contacts |
| `costs.email` | Integer | Unlocking the email |
| `costs.phone` | Integer | Unlocking the phone |
| `costs.email_phone` | Integer | Unlocking email and phone together |

Read the costs from `costs` instead of hard-coding them. The values are the same ones the dashboard shows when you unlock.

## Not enough credits [#not-enough-credits]

If your credits don't cover the action, the API answers with status `402` and deducts nothing. Webmetic checks this before it fetches any data.

So the API can also answer with `402` when Webmetic wouldn't have found the data at all. As with every API error, the error is in the `detail` field:

| Field | Meaning |
| --- | --- |
| `detail.error` | `INSUFFICIENT_CREDITS` |
| `detail.message` | Readable text about the error |
| `detail.required` | How many credits the action needs |
| `detail.available` | How many credits your account has |

In that case, buy more credits in the dashboard and then repeat the call. The API can't buy credits and doesn't top up your credits automatically. All error codes are listed under [Errors](https://webmetic.de/docs/en/api/fehler).

## Next steps [#next-steps]

- [Buy credits](https://webmetic.de/docs/en/credits#purchase-and-invoice): Top up credits in the dashboard and find the invoice.
- [Errors](https://webmetic.de/docs/en/api/fehler): Look up every status code and error code of the API.
- [Check your credits](https://webmetic.de/docs/en/api/referenz/contacts/credits): Try the `/contacts/credits` endpoint in the reference.