3CX CRM integration

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/v1/account/signup
  Content-Type: application/json
  
  {"email":"[email protected]","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: [email protected].