Add a UK phone number to an AI-built app

Why can't the app just create a number by itself?

UK numbers must be linked to a verified business before they go live, so the purchase step happens in Call Bullet rather than through the API.

Ofcom's numbering rules expect providers to know who holds each number and to stop numbers being used for scams. That means a real person confirms the business name and address once. After that, every number in the workspace is readable by your app, and new numbers appear in the API as soon as they are active.

This is the shortest honest path: a few minutes to order, verification usually the same working day, then one API call.

How do I get a number step by step?

The whole path, from nothing to a number showing in your app:

1. Sign up to Call Bullet and create a workspace for the business.
2. Open Numbers → Add numbers, pick a UK area code such as 0161 Manchester or 020 London, and choose where calls ring.
3. Upload the verification details when asked. The number shows as awaiting verification until it is approved.
4. Create an API key under Integrations → Developer API with workspaces:read and numbers:read.
5. Save the key as the server secret CALL_BULLET_API_KEY in your app.
6. Add the server function below and render the result.

See the UK numbers page for prices and area codes. Each number costs £5 a month with 100 inbound minutes included.

What does the code look like?

This server function lists live numbers with their placement, the phone they ring and calls in the last 30 days. It uses the shared helper from the developers hub.

import { cb } from "./call-bullet.server";

type CbNumber = {
  id: string;
  phone_number: string;
  placement: string | null;
  location: string | null;
  rings_to: string | null;
  calls: { total: number; answered: number; missed: number; last_call_at: string | null };
};

export async function listNumbers(workspaceId: string) {
  const { data } = await cb<{ data: CbNumber[] }>(
    `/workspaces/${workspaceId}/numbers?origin=call_bullet`,
  );
  return data.map((n) => ({
    number: n.phone_number,          // +441617..., format for display
    where: n.placement ?? "Website",
    ringsTo: n.rings_to,
    callsThisMonth: n.calls.total,
    missed: n.calls.missed,
  }));
}

Numbers are returned in E.164 format, such as +441612345678. Format them for display as 0161 234 5678 in UK interfaces.

Which fields will I use most?

These are the fields most apps need from the numbers endpoint.

Should the number on my site be static or swapped?

If the app is a website and you want to know which marketing made the phone ring, show swapped numbers from a website pool rather than one static number. The swap script changes the number per visitor and ties each call to its source.

If the app is an internal tool or the number is printed on vans and flyers, one fixed number is simpler. Read add call tracking to an AI-built site for the swap script, and static vs dynamic call tracking for the trade-offs.

How do I show the number to the right visitor?

For multi-branch businesses, filter numbers by location and show the matching one on each branch page. A Leeds page shows the 0113 number and a Bristol page the 0117 number, so callers reach the nearest team and reports split by branch.

Cache the list on the server for a few minutes rather than calling the API on every page view. Numbers rarely change, and caching keeps you well inside the 120 requests a minute limit.

What prompt do I paste into my AI app builder?

Paste this into the builder once your number is active.

Add my Call Bullet UK phone numbers to this app.
- Docs: https://callbullet.com/developers/api.md. Use only GET /workspaces and GET /workspaces/{id}/numbers.
- Ask me for my API key (cb_live_…, scopes workspaces:read and numbers:read) and store it as the server secret CALL_BULLET_API_KEY.
- Create a server function listNumbers(workspaceId) that returns phone_number, placement, location, rings_to and calls.total.
- Show the numbers on a Contact page formatted the UK way (0161 234 5678), with a tel: link.
- Cache results for 5 minutes. Never call the API from the browser.

What can go wrong?

Most problems are scope or timing.

• 403 forbidden: the key is not scoped to that workspace. Edit the key's workspaces.
• Empty list: the number is still awaiting verification, or you filtered origin=callrail_import.
• Wrong format on screen: you displayed E.164 directly; format it for UK readers.
• 401 unauthorized: the secret name or value is wrong, or the key was revoked.

How do I give each branch or client its own number?

Give each location its own number in Call Bullet and tag it with the location, then let your app pick the right one by reading the location field.

An agency building one app for several clients should keep each client in its own workspace. One key can be scoped to several workspaces, and every request is checked against that scope, so a dashboard for a Huddersfield garage can never show calls from a Bolton dentist. When you add a new client, create their workspace and numbers in Call Bullet, add the workspace to the key, and the app picks them up on its next request.

For a single business with several branches, one workspace with one number per branch is simpler. Your contact page reads the list once, groups it by location and shows the nearest branch's number based on the page the visitor is on. Reports then split calls by branch without any extra work.

What does it cost to run?

The API itself is free to use. You pay for the numbers and the minutes they carry, at the same prices as in the Call Bullet app.

Each number is £5 a month with 100 inbound minutes included, and calls are recorded and transcribed as standard. There is no separate developer plan, no per-request fee and no minimum term on API access. Most small apps stay well within the free request limits: a contact page that caches the numbers list for five minutes makes fewer than 300 requests a day.

• Numbers: £5 a month each, including 100 inbound minutes.
• API requests: no charge, within the documented rate limits.
• Recordings and transcripts: included with tracked calls.

Where should the number appear in the app?

Put the number where customers decide to call: the header on mobile, the contact page and any booking or quote page. A tel: link lets mobile visitors ring with one tap, and the swap script still changes the number if you add call tracking later.

Frequently asked questions