# 3CX CRM integration — inbound caller-name lookup

- Category: PBX & softphones
- Published: June 3, 2026 · Updated: June 11, 2026
- Canonical: https://numbers.online/docs/integrations/3cx

Add **Numbers Online** as a server-side CRM source so 3CX can resolve unknown
inbound callers to a business name, tenant-wide, with no client-side software.
When a call arrives from a number that is not already one of your 3CX contacts,
3CX asks Numbers Online for a caller-name (CNAM); if one is available it is shown
on the call.

> **Positioning.** The caller-name returned here is a *supplementary signal*
> derived from wholesale CNAM and number-range data. It is advisory, may be
> absent or stale, and is not an authoritative identity. Your operator keeps the
> routing decision and remains responsible for compliance. Numbers Online never
> asserts that a call is lawful, unlawful, "safe", or "spam".

## What it does

- Inbound calls only. When the caller is **not** an existing 3CX contact, 3CX
  performs a lookup and, on a hit, displays the business name (CNAM) on the call
  and in call history.
- Known 3CX contacts are **never overridden** — your local phonebook always wins.
- A number with no available name returns nothing to match, so 3CX simply shows
  the raw number. Nothing is invented (fail-open).

## Before you start

- A Numbers Online API key. Don't have one? Self-service signup:

  ```
  POST https://numbers.online/api/v1/account/signup
  Content-Type: application/json

  {"email":"you@example.com","name":"Your Company"}
  ```

  The key is returned exactly once. Free tier: 60 requests/min, unbilled.
  Docs: https://numbers.online/docs
- 3CX V18 or V20, with administrator access to the Admin Console.

## Install

1. Download the template:
   `https://numbers.online/integrations/3cx/numbers-online.crm.xml`
2. In the 3CX Admin Console, go to **Settings > CRM > Server side**.
3. Click **Add** and **upload** `numbers-online.crm.xml`.
4. Paste your key into the **Numbers Online API Key** field.
5. **Save.**
6. **Restart the 3CX System Service.** Server-side CRM template changes do not
   take effect until the service is restarted — this step is required, not
   optional.

## Verify it works

Use the built-in **CRM Test** button on the integration page (Settings > CRM >
Server side > Numbers Online). Enter a known business number in **+E.164** form
(e.g. `+14155552671`) and run the test:

- A number with a published name returns a contact with **CompanyName** set to
  the CNAM and **PhoneBusiness** equal to the number you searched.
- A number with no available name returns **no match** — expected behaviour, not
  an error.

## How matching behaves

3CX registers a contact only when the lookup yields **all** of: a contact URL, a
name field (company or person), and a phone number equal to the one searched.
This template emits a `CompanyName`, a `PhoneBusiness` that echoes the searched
number byte-for-byte, and a unique `ContactUrl` (`https://numbers.online/lookup/<E.164>`).

- **Existing 3CX contacts take priority.** If the caller is already in your
  3CX phonebook, that record is shown and no external name is applied.
- **No name available → raw number shown.** When Numbers Online has no CNAM for a
  number (no name on file, no supplier, or a privacy-suppressed listing), the
  template's match rule does not fire and 3CX displays the number as-is.

## Limitations

- **No spam/risk score in the 3CX contact panel.** 3CX's server-side CRM contact
  panel can only surface name, company, and phone fields — there is no output
  type for a risk score. The Numbers Online `spam_score` is therefore **not**
  shown in 3CX. (It would be technically possible to fold a risk word into the
  displayed company name, but this template intentionally does **not** do so, to
  keep the displayed name clean and to avoid presenting a low-confidence signal
  as an identity. Any risk-tagging belongs in an opt-in, operator-configured
  surface — see the plain-text CID endpoint in the API docs.)
- **Inbound contact lookup only.** This integration resolves names for incoming
  calls. It does not create, sync, or write back records, and does not journal
  calls into an external CRM.
- **Advisory data.** CNAM coverage is partial and reflects number-range and
  wholesale data, not real-time porting. Treat a missing name as "unknown",
  never as a negative signal.

## Fail-open behaviour

If Numbers Online is slow or unreachable, 3CX proceeds normally and shows the raw
number — call setup is never blocked or delayed by a failed lookup. The template
caps concurrency (`MaxConcurrentRequests="2"`) so bursts of inbound calls cannot
overwhelm the lookup path. No raw phone numbers or API keys are logged by this
integration.

## Pricing

Lookups are billed per dip: **$0.004** per lookup that performs a fresh CNAM dip,
**$0.002** for a cache hit or when no supplier returns a name. Invalid numbers are
**free**. The free tier is unbilled at **60 requests/min**. Because 3CX queries
only for callers who are not already local contacts, billable volume tracks your
unknown-caller traffic, not total call volume.

## Troubleshooting

- **Nothing happens / no name on calls.** Confirm you **restarted the 3CX System
  Service** after uploading or editing the template — this is the most common
  cause. Then re-run **CRM Test**.
- **CRM Test returns no match for a number you expected to resolve.** Coverage is
  partial; many numbers (especially mobiles and privacy-suppressed listings) have
  no published CNAM. This is expected — 3CX will show the raw number.
- **Every lookup fails.** Re-check the API key in the integration's
  **Numbers Online API Key** field. A `401` (bad/missing key) or `402`
  (insufficient balance) causes the lookup to return no contact; top up or reissue
  the key. The integration still fails open — calls keep working.
- **Numbers searched without a country code.** 3CX sends the caller number in
  +E.164 form via this template. If you test with a bare national number it may
  not resolve; use the full `+<countrycode>...` form in **CRM Test**.

For API keys, higher rate limits, or volume pricing: **api@numbers.online**.

## Keys & references

Keys are self-service at https://numbers.online/docs — shown once, stored only as a hash.
Machine-readable schema: https://numbers.online/api/spec · all guides: https://numbers.online/md/docs/integrations

- Previous guide: [FreeSWITCH & FusionPBX caller ID lookup](https://numbers.online/md/docs/integrations/freeswitch-fusionpbx)
- Next guide: [MicroSIP caller ID for Windows](https://numbers.online/md/docs/integrations/microsip)

---

Numbers Online — community-powered phone-number trust signals. Every figure on this
page is a supplementary, low-confidence signal — advisory, not a verdict on any number
or its owner.

- Canonical page (HTML): https://numbers.online/docs/integrations/3cx
- Report a call: https://numbers.online/report · Listed in error? Request removal: https://numbers.online/opt-out
- Machine guide to the phone-intelligence API: https://numbers.online/llms.txt · OpenAPI: https://numbers.online/api/spec