# Voice and messaging

Give each customer a profile with their own numbers, read and bill their calls and SMS by your own tenant id, and route events back to them.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

By the end of this page, each of your customers has their own numbers, and you can read, bill and monitor their calls and SMS by your own tenant id.

## How usage maps to a customer

Numbers live in a profile. A call or text belongs to the profile of the number it went through, so one profile per customer splits every usage figure per customer.

Set your tenant id as the profile's `externalId` and the usage endpoints take it as a filter, so you never store our profile id.

| Endpoint | Per-profile options |
|---|---|
| [`GET /v1/usage/calls`](/usage/get-calls-usage) | `profileId` or `externalId` filter, `groupBy=profile` |
| [`GET /v1/usage/sms`](/usage/get-sms-usage) | `profileId` or `externalId` filter, `groupBy=profile` |
| [`GET /v1/usage`](/usage/get-usage) (with `range`) | Billed spend per profile: `profileId` or `externalId` filter, `groupBy=profile` |
| `GET /v1/usage-stats` | A `profile` block with the profile's connected accounts |
| [`GET /v1/voice/calls`](/voice/list-voice-calls) | `profileId` or `externalId` filter on the call history |

## Before you start

You need a profile per customer with their `externalId`, as in the [core model](/multi-tenant), and an API key that can read usage.

## Step 1: Buy numbers into the profile

Pass the customer's `profileId` when you buy the number, so its calls and texts count toward that customer.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: number } = await zernio.phonenumbers.purchasePhoneNumber({
  body: { profileId: '66a1f0c2a4b9d3e8f1a2b3c4', country: 'US' },
});
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

number = client.phone_numbers.purchase_phone_number(
    profile_id="66a1f0c2a4b9d3e8f1a2b3c4",
    country="US",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/phone-numbers/purchase" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "66a1f0c2a4b9d3e8f1a2b3c4", "country": "US" }'
```
</Tab>
</Tabs>

A number bought without `profileId` goes to your default profile, and its usage counts there.

## Step 2: Read one customer's usage

Call the usage endpoints with `externalId`, your own tenant id.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data: calls } = await zernio.usage.getCallsUsage({
  query: { externalId: 'cus_8f3a2', since: '2026-10-01T00:00:00Z', until: '2026-11-01T00:00:00Z' },
});

const { data: sms } = await zernio.usage.getSmsUsage({
  query: { externalId: 'cus_8f3a2', since: '2026-10-01T00:00:00Z', until: '2026-11-01T00:00:00Z' },
});
```
</Tab>
<Tab value="Python">
```python
calls = client.usage.get_calls_usage(
    external_id="cus_8f3a2",
    since="2026-10-01T00:00:00Z",
    until="2026-11-01T00:00:00Z",
)

sms = client.usage.get_sms_usage(
    external_id="cus_8f3a2",
    since="2026-10-01T00:00:00Z",
    until="2026-11-01T00:00:00Z",
)
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/usage/calls?externalId=cus_8f3a2&since=2026-10-01T00:00:00Z&until=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Response (`200`), calls:

```json
{
  "since": "2026-10-01T00:00:00.000Z",
  "until": "2026-11-01T00:00:00.000Z",
  "groupBy": null,
  "profile": { "profileId": "66a1f0c2a4b9d3e8f1a2b3c4", "externalId": "cus_8f3a2" },
  "totals": {
    "calls": 214,
    "answered": 188,
    "minutes": 731.5,
    "billableUSD": 9.1442,
    "metaUSD": 0,
    "brandedCalls": 0,
    "brandedCallUSD": 0
  },
  "groups": []
}
```

`billableUSD` is what we bill you for these calls, so it is the figure to rebill. SMS returns volumes (`sent`, `received`, `total`): its cost is carrier-rated later and lands on the invoice.

`GET /v1/voice/calls?externalId=cus_8f3a2` lists the same customer's call history.

## Step 3: Bill every customer in one call

Add `groupBy=profile` to get one group per customer. Each group carries `profileId` and `externalId`, so you can write invoice lines without a second lookup.

```bash
curl "https://zernio.com/api/v1/usage/calls?groupBy=profile&since=2026-10-01T00:00:00Z&until=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

```json
{
  "groupBy": "profile",
  "totals": { "calls": 391, "billableUSD": 15.802 },
  "groups": [
    { "key": "66a1f0c2a4b9d3e8f1a2b3c4", "profileId": "66a1f0c2a4b9d3e8f1a2b3c4", "externalId": "cus_8f3a2", "calls": 214, "billableUSD": 9.1442 },
    { "key": "66a1f0c2a4b9d3e8f1a2b3c5", "profileId": "66a1f0c2a4b9d3e8f1a2b3c5", "externalId": "cus_1c9d0", "calls": 177, "billableUSD": 6.6578 }
  ]
}
```

The group rows are shortened here: each carries the same fields as `totals`.

For the full billed spend per customer across every product (numbers, calls, SMS, messages), call `GET /v1/usage?range=prev-cycle&groupBy=profile`. Its `attribution.groups` carry `profileId` and `externalId` the same way.

## Step 4: Route events to the customer

Call and message webhooks carry the profile with your id in `profiles[]`:

```json
{
  "event": "call.ended",
  "profiles": [{ "id": "66a1f0c2a4b9d3e8f1a2b3c4", "externalId": "cus_8f3a2" }],
  "call": { "...": "..." }
}
```

Route on `profiles[0].externalId`. The [webhooks overview](/webhooks) covers signatures and retries.

## Per-profile limits

Cap each customer's calling on their profile, so one tenant can never run up another's bill. Set the caps when you create or [update the profile](/profiles/update-profile):

| Field | Caps, for calls on the profile's numbers |
|---|---|
| `maxOutboundCallsPerHour` | Outbound calls per rolling hour |
| `maxDailyCallSpendUsd` | Billed call spend in USD per rolling 24 hours |
| `maxForwardedMinutesPerDay` | Minutes forwarded to a phone per rolling 24 hours |

Send `null` on an update to clear a cap. Profile caps apply inside the team limits, never above them.

`GET /v1/profiles/{id}/limits` returns each limit with `limit`, `used` and `remaining`. `profile` holds the profile's own caps (a null `limit` means none is set).

`team` holds the limits they sit inside, including `dailyCallSpendUsd` and `dailyForwardSpendUsd` in billed USD, the same unit as `maxDailyCallSpendUsd`.

```bash
curl "https://zernio.com/api/v1/profiles/66a1f0c2a4b9d3e8f1a2b3c4/limits" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

Past any limit, an outbound call returns `429 call_limit_reached` and a call forwarded to a phone goes to voicemail. A profile-scoped key can read its own profile's limits.

## How it behaves

- `profileId` and `externalId` are mutually exclusive. Send one.
- A call or text follows the number's current profile. Moving a number to another profile moves its history with it.
- Usage on numbers outside any of your profiles, such as alphanumeric SMS sender IDs, counts in `totals` but in no group.
- A profile-scoped API key reads only its own profiles, even without a filter: `totals`, groups and the call history cover those profiles only. Give each tenant a key scoped to its profile and it can never read another tenant's usage.
- On a bare `GET /v1/usage`, `profileId` and `externalId` are ignored. Use `GET /v1/usage-stats` for the per-profile snapshot.

## If it fails

| Error | Cause | Fix |
|---|---|---|
| `404 profile_not_found`, `param: externalId` | No profile you can read carries that `externalId` | Check the id, or set it on the profile with `PUT /v1/profiles/{profileId}` |
| `404 profile_not_found`, `param: profileId` | The profile is not in your team, or outside the API key's profiles | Use a key scoped to that profile |
| `400 invalid_field_value`, `param: externalId` | Two profiles in your team share that `externalId` | Filter by `profileId` instead |
| `400`, `param: externalId` | Both `profileId` and `externalId` were sent | Send one |

## Related

- [Build a platform](/multi-tenant): the profile-per-customer model.
- [Get calls usage](/usage/get-calls-usage) and [Get SMS usage](/usage/get-sms-usage): every parameter and field.
- [Get usage](/usage/get-usage): billed spend per profile.
- [List phone calls](/voice/list-voice-calls): call history per profile.
- [Buy a phone number](/phone-numbers/purchase-phone-number): numbers are bought into a profile.
- [Get profile limits](/profiles/get-profile-limits): per-profile call caps and their usage.
- [Webhooks](/webhooks): `profiles[]` on every event.