Telephony and contact center

Check phone numbers, phone complaints and country codes in RingCentral

Check the numbers that arrive in RingCentral webhook notifications about SMS messages: is the number well formed, what country and format does it belong to, and what type does the numbering plan give it.

Why the data matters in RingCentral

In a RingCentral account every SMS thread, call log and click-to-dial action hangs on a phone number, and an app that listens to push notifications for instant SMS message events sees those numbers the moment they arrive. A number typed with a stray digit, a missing country code or a toll-free line in a field meant for texting turns into a dial that never connects or a message that goes nowhere, and the rep only finds out after the call attempt. Cleaning the number as the event arrives keeps the log, the contact record and the dialer pointing at numbers that can be dialed.

What LookValid checks

LookValid checks for RingCentral
Product	What it does here	Credits
Phone Numbering-Plan Validation	Confirms a number fits its country numbering plan and returns it in one canonical international format, so contact records stop holding five spellings of the same number. Returns the number type the plan assigns (mobile, fixed line, toll free, VoIP and others), so you can route texting to mobile numbers only. It does not say whether the line is active.	1 credit per valid number
Phone Spam Check	Returns how many public consumer complaints exist for a number, which helps a team judge an unknown inbound caller. Complaints are reports, not a verdict.	1 credit per number with complaints on record
Country Calling Codes	Explains a calling code and the regions that share it, useful when an agent has to dial a country that is new to them.	1 credit per lookup (an unknown code, country or name is free)

Connect it in four steps

Sign up for a LookValid account and add a key under API keys in the dashboard.
Store the key as the LOOKVALID_API_KEY environment variable of the service that is your webhook delivery address, next to the RC_APP_CLIENT_ID style app credentials it already reads from its .env file, and keep it out of the code and out of the notification payloads.
When a notification carrying a phone number reaches the webhook address, call the phone endpoint with that number; treat found:false as a number to flag for a person, and stop with the error code when the answer is an error.
Save normalizedNumber as the number you dial, dialDisplay as what agents read on screen, and numberCountry on the contact so call routing can use it.

A small web service of yours that acts as the delivery address of a RingCentral webhook subscription: it answers the Validation-Token handshake, then cleans the number in each notification before it is stored. The call is POST https://YOUR_API_HOST/v1/phone and costs 1 credit per valid number.

validateRingCentralPhone.mjs

1const API_URL = "https://YOUR_API_HOST/v1/phone";
2
3export async function validateRingCentralPhone(value) {
4  const response = await fetch(API_URL, {
5    method: "POST",
6    headers: {
7      Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
8      "Content-Type": "application/json",
9    },
10    body: JSON.stringify({
11      "phone": value,
12    }),
13  });
14  const result = await response.json();
15  if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
16  if (!result.found) return null;
17  return {
18      "normalizedNumber": result.data?.e164 ?? null,
19      "numberCountry": result.data?.country ?? null,
20      "dialDisplay": result.data?.national_format ?? null,
21  };
22}

Where each response field goes in RingCentral
Response field	Goes into
data.e164	normalizedNumber
data.country	numberCountry
data.national_format	dialDisplay

The recipe returns nothing when the lookup finds nothing, which costs no credits for this product, and stops with the error code and fix on a failed request.

Without code

If your RingCentral notifications already feed an automation platform, you can skip the code: add a generic HTTP request step right after the trigger that carries the number, send the number to the phone endpoint with your key in the Authorization header, and map the returned number and country into the next step. The step needs no dedicated app for LookValid, only the URL, the header and a JSON body.

REST and MCPOne shared credit balance

Questions

How many credits does a RingCentral number check cost?

Each check is billed like any other phone lookup, and the amount is on the pricing page.

Can the check tell me a number is switched on or who the carrier is?

No. The phone check reads the numbering plan only, so it tells you the number is well formed and what type the plan assigns. It cannot tell you the line is live or which company serves it.

Where does the API key live?

In the environment of the service that handles your events. It is sent as a bearer token on each request and never needs to appear in a contact record or a call log.

Sources

RingCentral developer guide: Webhook Notifications Quick Start https://developers.ringcentral.com/guide/notifications/webhooks/quick-start, read 2026-10-18
LookValid API reference: Phone Numbering-Plan Validation https://lookvalid.com/docs/api/phone, read 2026-10-18

LookValid is run by Meralume Labs. It is not connected to, endorsed by or a partner of any company or product named on this page, and every product name belongs to its owner.

LookValid bills every lookup in credits from one shared balance, so the same key works for each check above.

See Phone Numbering-Plan Validation